README

This is a very simple static utility class that gives access to the pbcopy and pbpaste interface on MacOS and other systems that support those shell commands. This utility is primarily useful in developing PHP command line tools. It endeavors to comply fully with PRS-1, PRS-2, and PRS-4.

This project also uses the thephpleague/skeleton repository for component boilerplate.

Install

Via Composer

$ composer require Dlindberg/Pasteboard

Usage

Pasteboard has three methods:

Get

Retrieves a value from the clipboard.

Pasteboard::get();

Parameters: None.

Returns: The contents of the host computers clipboard or false if the clipboard is empty or fails to return a value.

Note: no filters or santization is applied to the return value and it is prudent to treat the value as unsafe user input for the purposes of your application.

Set

Copies a value to the clipboard.

Pasteboard::set(string $value);

Parameters $value any value that the pasteboard on the host computer accepts. The function does not validate that the value is safe or valid before attempting to pass it to the host computer. If you are sending user input, or the results of an http request to the computer's clipboard it is prudent ensure that whatever is sent to the clipboard is safe for the context you intend to paste it to.

Returns: true on success or false on failure.

Set Array

Sends an array of values one at a time to the clipboard pausing between each send. The function also has some advanced options defined in the $options array.

Pasteboard::setArray(array $values, array $options)

Parameters

$values an array of values you wish to send to the host computer. The same notes as in set apply to each value.
$options an optional settings array. Available options:
- reset when true the original contents of the clipboard will be restored at the end of execution. Default: false.
- wait amount of time in seconds to wait between set() operations. Default 1.
- depth Specified recursion depth. Default: 0, nested arrays will be skipped.
- heartbeat a user defined closure function that will execute each time the clipboard is set. This function overrides the default $hearbeat function. Therefore, the wait parameter is ignored when a hearbeat is passed. The function should return a truthy value if execution should continue and a falsy value to terminate execution. Heartbeat is passed the result of set().

Returns: true on success or false on failure.

Note: Without an advanced clipboard manager on the host machine, or passing a heartbeat function sending more than two to three items to clipboard will rapidly become untenable.

Change log

Please see CHANGELOG for more information on what has changed recently.

Testing

$ composer test

Contributing

Please see CONTRIBUTING and CODE_OF_CONDUCT for details.

Security

If you discover any security related issues, please email dane@lindberg.xyz instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.

dlindberg / pasteboard

Maintainers

Details