Download the PHP package unicorn-fail/php-option without Composer
On this page you can find all versions of the php package unicorn-fail/php-option. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package php-option
unicorn-fail/php-option
A highly extensible replacement for phpoption/phpoption with
TypedOptionsupport.
An Option is intended for cases where you sometimes might return a value
(typically an object), and sometimes you might return no value (typically null)
depending on arguments, or other runtime factors.
Often times, you forget to handle the case where no value is returned. Not intentionally of course, but maybe you did not account for all possible states of the system; or maybe you indeed covered all cases, then time goes on, code is refactored, some of these your checks might become invalid, or incomplete. Suddenly, without noticing, the no value case is not handled anymore. As a result, you might sometimes get fatal PHP errors telling you that you called a method on a non-object; users might see blank pages, or worse.
On one hand, an Option forces a developer to consciously think about both cases
(returning a value, or returning no value). That in itself will already make your code more
robust. On the other hand, the Option also allows the API developer to provide
more concise API methods, and empowers the API user in how he consumes these methods.
📦 Installation
This project can be installed via Composer:
Basic Usage
Using Option in your API
If you are consuming an existing library, you can also use a shorter version
which by default treats null as None, and everything else as Some case:
After:
Case 1: always require an Entity when invoking code
Case 2: fallback to default value if not available
No More Boiler Plate Code
Before:
After:
No more control flow exceptions
Before:
After:
Concise null handling
Before:
After:
Chaining multiple alternative Options
If you need to try multiple alternatives, the orElse method allows you to
do this very elegantly.
Before:
After:
The first option which is non-empty will be returned. This is especially useful with lazily evaluated options.
Lazily evaluated Options
The above example has a flaw where the option chain would need to evaluate all options when the method is called. This creates unnecessary overhead if the first option is already non-empty.
Fortunately, this can be easily solved by using LazyOption which takes a callable
that will be invoked only if necessary:
Typed options
In cases where you need a specific PHP type returned (e.g. string, boolean, number, etc.) the TypedOption class
may provide you with more flexibility:
Before:
After:
📓 API Documentation
Official and extensive API documentation coming soon (PRs are welcome).
🏷️ Versioning
SemVer is followed closely. Minor and patch releases should not introduce breaking changes to the codebase.
This project's initial release will start at version 1.6.0 to stay in line with existing phpoption/phpoption releases.
🛠️ Support & Backward Compatibility
Version <1.6.0
- This project will not patch any bugs, address any security related issues, or make another release. Please upgrade, it should be as simple as:
Version >=1.6.0 <2.0.0
- This project will keep backward compatibility with phpoption/phpoption and continue running the original tests to ensure previous namespaces and implementation are still functional.
- The following classes are automatically registered as aliases so existing code should still remain functional (see known caveats below):
PhpOption\LazyOption=>UnicornFail\PhpOption\LazyOptionPhpOption\None=>UnicornFail\PhpOption\NonePhpOption\Option=>UnicornFail\PhpOption\OptionPhpOption\Some=>UnicornFail\PhpOption\Some
- The following methods have been deprecated, use their replacements instead:
Option::ensure()=>Option::create()Option::fromValue()=>Option::create()Option::fromArraysValue()=>Option::pick()Option::fromReturn()=>Option::create()$option->ifDefined()=>$option->forAll()
- Known caveats:
- The minor alterations due testing/environment issues.
- PHP 5.3 has a weird bug where class aliases aren't being registered properly. Because of this, the classes had
to be extended from their respective replacements. This, unfortunately, prevents
\PhpOption\Some,\PhpOption\Noneand\PhpOption\LazyOptionfrom being able to be extended directly from\PhpOption\Option. If your code implements anything resembling$option instanceof Option, these will fail. You will need to change these to$option instance of \UnicornFail\PhpOption\OptionInterfaceinstead.
Version 2.0.0
- This project plans to remove support for all of
PHP 5,PHP 7.0,PHP 7.1and backward compatibility with phpoption/phpoption.
⛔ Security
To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure with us.
👷♀️ Contributing
Contributions to this library are welcome!
Please see CONTRIBUTING for additional details.
🧪 Testing
Local development (ignore changes to composer.json):
With coverage:
🚀 Performance Benchmarks
Of course, performance is important. Included in the tests is a performance benchmark which you can run on a machine of your choosing:
At its core, the overhead incurred by using Option comes down to the time that it takes to
create one object, the Option wrapper. It will also need to perform an additional method
call to retrieve the value from the wrapper. Depending on your use case(s) and desired
functionality, you may encounter varied results.
Average Overhead Per Invocation*
In the table above, these benchmarks rarely are well under a fraction of a microsecond. Many of them measure in nanoseconds; with newer PHP versions decreasing the overhead even more over time.
Unless you plan to call a method hundreds of thousands of times during a request, there is no reason
to stick to the object|null return value; better give your code some options!
*Average based on the comparison of creating a single object vs. the creation of a wrapper and a single method call; iterated over 10000 times and then calculating the difference.
👥 Credits & Acknowledgements
- Mark Carver (twitter) (github)
- Johannes (twitter) (github)
- All Contributors
📄 License
unicorn-fail/php-option is licensed under the Apache 2.0 license. See the LICENSE file for more details.
