imliam / php-modifiers
Apply optional modifiers to PHP functions
Requires
- php: ^7.2
Requires (Dev)
- phpunit/phpunit: ^7.0
This package is auto-updated.
Last update: 2024-10-20 12:43:56 UTC
README
Adds the ability to apply a range of optional modifiers ! @ ~ + - when calling your class methods to augment them with a unique syntax.
For example, we may have a class where each of the following may do different things:
Slack::say('Hello world'); // 'Hello world' !Slack::say('Hello world'); // 'HELLO WORLD' @Slack::say('Hello world'); // 'Someone said "Hello world"' @!Slack::say('Hello world'); // 'Someone said "HELLO WORLD"'
💾 Installation
You can install the package with Composer using the following command:
composer require imliam/php-modifiers:^1.0.0
📝 Usage
This package's functionality is exposed through the HasModifiers trait, which can be applied to a class:
class Example { use HasModifiers; }
With the trait applied to the class, you must also define the class methods that can have modifiers used. This can be done by setting a static $modifierAliases property on the class.
This property should be an array that contains pairs of the class and method name that can be used.
For example if we wanted the say method on the current class to be able to use modifiers:
public static $modifierAliases = [ [self::class, 'say'], ];
With this set up, inside the method we can now check if certain modifiers have been used by calling the static::hasModifier() method:
public static function say($string) { if (static::hasModifier('!')) { echo strtoupper($string); return; } echo $string; }
With it all in place, we can now call our method either with or without the modifier to get the desired behaviour:
Example::say('Hello world'); // 'Hello world' !Example::say('Hello world'); // 'HELLO WORLD'
Global Functions
If we wanted to register a global function that can accept modifiers, we can use one to call our class method, as well as registering it as an alias by adding it to the $modifierAliases property.
function say($string) { return Example::say($string); } Example::$modifierAliases[] = 'say';
The function will now work in the same way as before:
say('Hello world'); // 'Hello world' !say('Hello world'); // 'HELLO WORLD'
The Modifiers
There are five modifiers available to use. It is very important to note that as they are all also regular operators in PHP, each of them have their own quirks that might change the expected behaviour and return values of the methods.
Using them
Due to this, it would make sense to only use these modifiers on void functions that are not expected to return anything of use.
! Exclamation Mark
Do not use the return value with this modifier.
The exclamation mark is a logical operator in PHP that negates the value to the opposite boolean. This means that any truthy value that is returned will be false, and any falsy value returned will be true.
+ Plus Symbol
Do not use the return value with this modifier.
The plus symbol is an identity arithmetic operator in PHP. Used as a modifier, it will attempt to cast the return value to an integer or float.
- Minus Symbol
Do not use the return value with this modifier.
The plus symbol is a negative identity arithmetic operator in PHP. Used as a modifier, it will attempt to cast the return value to an integer or float.
~ Tilde Symbol
Do not use the return value with this modifier.
The tilde symbol is a bitwise operator in PHP. However, as the operator itself performs a bitwise operation, any method using this operator must return an integer value, or something that can be cast to one.
@ "At" Symbol
You can use the return value with this modifier.
The "at" symbol is an error suppression operator in PHP that hides and ignores any errors that occur in the proceeding statement - meaning errors that might be within your method will be unexpectedly ignored.
However, this is the only one of the operators that does not alter the return value of the method.
public static function hasSomething() { if (static::hasModifier('@')) { trigger_error("An error should occur here, but it gets ignored…"); return 'A modified value…'; } return 'A non-modified value…'; } echo Example::hasSomething(); // 'A non-modified value…' echo @Example::hasSomething(); // 'A modified value…'
How It Works
✨ Magic ✨
The modifier functionality works by taking a stack trace at the point the method was called, finding the point aliased method was called further up in the stack trace. Once these aliases are found, the file is read as a string and the PHP source tokens are parsed to find the operators that came before it.
This was originally seen in the Kint package as a way to quickly augment how your variables are displayed while debugging. Because it was designed for this environment, great performance was not a huge concern. Following stack traces and parsing source code are generally slow operations in PHP, so take it with a grain of salt and don't abuse it in large production applications.
Check the source code to see how it works in more depth. This package is a stripped down version of Kint's implementation that fits in a couple of small source files.
✅ Testing
composer test
🔖 Changelog
Please see the changelog file for more information on what has changed recently.
⬆️ Upgrading
Please see the upgrading file for details on upgrading from previous versions.
🎉 Contributing
Please see the contributing file and code of conduct for details on contributing to the project.
🔒 Security
If you discover any security related issues, please email liam@liamhammett.com instead of using the issue tracker.
👷 Credits
- Liam Hammett
- Kint and all of its contributors for the implementation
- All Contributors
♻️ License
The MIT License (MIT). Please see the license file for more information.