-
-
Notifications
You must be signed in to change notification settings - Fork 40
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge remote-tracking branch 'upstream/4.0.x' into 3.19.x-merge-up-in…
…to-4.0.x_BwqaMWP9 # Conflicts: # psalm-baseline.xml # src/SplPriorityQueue.php
- Loading branch information
Showing
18 changed files
with
528 additions
and
515 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,125 @@ | ||
| # Console Helper | ||
|
|
||
| Writing one-off scripts or vendor binaries for a package is often problematic: | ||
|
|
||
| - You need to parse arguments manually. | ||
| - You need to send output to the console in a meaningful fashion: | ||
| - Using `STDOUT` for meaningful, expected output | ||
| - Using `STDERR` for error messages | ||
| - Ensuring any line breaks are converted to `PHP_EOL` | ||
| - Optionally, using console colors to provide context, which means: | ||
| - Detecting whether or not the console supports colors in the first place | ||
| - Providing appropriate escape sequences to produce color | ||
|
|
||
| `Laminas\Stdlib\ConsoleHelper` helps to address the second major bullet point and | ||
| all beneath it in a minimal fashion. | ||
|
|
||
| ## Usage | ||
|
|
||
| Typical usage is to instantiate a `ConsoleHelper`, and call one of its methods: | ||
|
|
||
| ```php | ||
| use Laminas\Stdlib\ConsoleHelper; | ||
|
|
||
| $helper = new ConsoleHelper(); | ||
| $helper->writeLine('This is output'); | ||
| ``` | ||
|
|
||
| You can optionally pass a PHP stream resource to the constructor, which will be | ||
| used to determine whether or not color support is available: | ||
|
|
||
| ```php | ||
| $helper = new ConsoleHelper($stream); | ||
| ``` | ||
|
|
||
| By default, it assumes `STDOUT`, and tests against that. | ||
|
|
||
| ## Available methods | ||
|
|
||
| `ConsoleHelper` provides the following methods. | ||
|
|
||
| ### colorize | ||
|
|
||
| - `colorize(string $string) : string` | ||
|
|
||
| `colorize()` accepts a formatted string, and will then apply ANSI color | ||
| sequences to them, if color support is detected. | ||
|
|
||
| The following sequences are currently supported: | ||
|
|
||
| - `<info>...</info>` will apply a green color sequence around the provided text. | ||
| - `<error>...</error>` will apply a red color sequence around the provided text. | ||
|
|
||
| You may mix multiple sequences within the same stream. | ||
|
|
||
| ### write | ||
|
|
||
| - `write(string $string, bool $colorize = true, resource $stream = STDOUT) : void` | ||
|
|
||
| Emits the provided `$string` to the provided `$stream` (which defaults to | ||
| `STDOUT` if not provided). Any EOL sequences are convered to `PHP_EOL`. If | ||
| `$colorize` is `true`, the string is first passed to `colorize()` as well. | ||
|
|
||
| ### writeline | ||
|
|
||
| - `writeLine(string $string, bool $colorize = true, resource $stream = STDOUT) : void` | ||
|
|
||
| Same as `write()`, except it also appends a `PHP_EOL` sequence to the `$string`. | ||
|
|
||
| ### writeErrorMessage | ||
|
|
||
| - `writeErrorMessage(string $message)` | ||
|
|
||
| Wraps `$message` in an `<error></error>` sequence, and passes it to | ||
| `writeLine()`, using `STDERR` as the `$stream`. | ||
|
|
||
| ## Example | ||
|
|
||
| Below is an example class that accepts an argument list, and determines how and | ||
| what to emit. | ||
|
|
||
| ```php | ||
| namespace Foo; | ||
|
|
||
| use Laminas\Stdlib\ConsoleHelper; | ||
|
|
||
| class HelloWorld | ||
| { | ||
| private $helper; | ||
|
|
||
| public function __construct(ConsoleHelper $helper = null) | ||
| { | ||
| $this->helper = $helper ?: new ConsoleHelper(); | ||
| } | ||
|
|
||
| public function __invoke(array $args) | ||
| { | ||
| if (! count($args)) { | ||
| $this->helper->writeErrorMessage('Missing arguments!'); | ||
| return; | ||
| } | ||
|
|
||
| if (count($args) > 1) { | ||
| $this->helper->writeErrorMessage('Too many arguments!'); | ||
| return; | ||
| } | ||
|
|
||
| $target = array_shift($args); | ||
|
|
||
| $this->helper->writeLine(sprintf( | ||
| '<info>Hello</info> %s', | ||
| $target | ||
| )); | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## When to upgrade | ||
|
|
||
| `ConsoleHelper` is deliberately simple, and assumes that your primary need for | ||
| console tooling is for output considerations. | ||
|
|
||
| If you need to parse complex argument strings, we recommend using | ||
| [symfony/console](http://symfony.com/doc/current/components/console.html), | ||
| as this package provides those capabilities, as well as far more colorization | ||
| and console feature detection facilities. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
| # Migration from Version 3 to 4 | ||
|
|
||
| Version 4 of `laminas-stdlib` contains a number of backwards incompatible changes. This guide is intended to help you upgrade from the version 3 series to version 4. | ||
|
|
||
| ## New Features | ||
|
|
||
| ### Parameter, Property and Return Type Hints Have Been Added Throughout | ||
|
|
||
| All classes have been updated to make use of parameter and return types. In general usage, this should not pose too many problems, providing you have been passing the previously documented types to the methods that have changed, however, it is advisable to audit your existing usage of the library for potential type errors. A static analysis tool like Psalm or PHPStan will help you with this. | ||
|
|
||
| The addition of property, parameter and return types will cause fatal errors for extending classes that re-define those properties or override changed methods. If you have extended from any classes in laminas-stdlib, you should check that property types and method signatures are compatible and update them if they are not aligned. | ||
|
|
||
| ### `PriorityQueue::toArray()` Now Returns Data in Order of Priority | ||
|
|
||
| In previous versions, `PriorityQueue::toArray()` returned data in insertion order. This method now returns data in priority order making it effectively the same as `iterator_to_array($queue)`, with the exception that you can pass extraction flags to `PriorityQueue::toArray()`. | ||
|
|
||
| ## Removed Features | ||
|
|
||
| - The `JsonSerializable` interface, deprecated in the 3.x series has been removed | ||
| - `ArrayUtils::filter()`, deprecated in the 3.x series and its related constants `ArrayUtils::ARRAY_FILTER_USE_BOTH` and `ArrayUtils::ARRAY_FILTER_USE_KEY` have been removed | ||
|
|
||
| ## Signature Changes | ||
|
|
||
| ### Breaking Changes to Return Types in Iterable Classes | ||
|
|
||
| A number of Queue, Stack and Heap implementations have different return types in order to align with the built-in PHP interfaces that they implement such as `Iterator` or `IteratorAggregate` etc. | ||
|
|
||
| #### `insert()` Signature Change for Iterable Types | ||
|
|
||
| PHP's built-in `\SplPriorityQueue`, `\SplHeap`, `\SplMinHeap` and other similar classes return `true` from the `insert()` method. Classes that either extend from or have similar semantics to these built-in types previously had varying return types such as `void`, `self`. From version 4, the method signature for `insert()` where implemented has been changed to `bool` _(true)_. | ||
|
|
||
| - `Laminas\Stdlib\SplPriorityQueue::insert()` previously returned `void`. This has been changed to `bool` to align with `\SplPriorityQueue` | ||
| - `Laminas\Stdlib\PriorityQueue::insert()` previously returned `self`. This has been changed to `bool` for consistency | ||
| - `Laminas\Stdlib\PriorityList::insert()` previously returned `void`. This has been changed to `bool` for consistency | ||
| - `Laminas\Stdlib\FastPriorityQueue::insert()` previously returned `void`. This has been changed to `bool` for consistency | ||
|
|
||
| #### Other Method Signature Changes | ||
|
|
||
| ##### `Laminas\Stdlib\PriorityList` | ||
|
|
||
| - `next()` previously returned `false` or the node value at the next index and now returns `void` to align with the `Iterator` interface. | ||
| - `setPriority()` previously returned `self` and now returns `void` for consistency. | ||
|
|
||
| ## Deprecations | ||
|
|
||
| None. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.