Download the PHP package imliam/php-modifiers without Composer

PHP Modifiers

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:

• PHP Modifiers
  • 💾 Installation
  • 📝 Usage
    • Global Functions
  • The Modifiers
    • ! Exclamation Mark
    • + Plus Symbol
    • - Minus Symbol
    • ~ Tilde Symbol
    • @ "At" Symbol
  • How It Works
  • ✅ Testing
  • 🔖 Changelog
  • ⬆️ Upgrading
  • 🎉 Contributing
    • 🔒 Security
  • 👷 Credits
  • ♻️ License

💾 Installation

You can install the package with Composer using the following command:

📝 Usage

This package's functionality is exposed through the HasModifiers trait, which can be applied to a class:

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:

With this set up, inside the method we can now check if certain modifiers have been used by calling the static::hasModifier() method:

With it all in place, we can now call our method either with or without the modifier to get the desired behaviour:

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.

The function will now work in the same way as before:

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.

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

🔖 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 code of conduct for details on contributing to the project.

🔒 Security

If you discover any security related issues, please email [email protected] 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.