Download the PHP package activecollab/utils without Composer

Utils

This package is a playground for "little" PHP utilities that we use every day. They are not complex or big enough to justify a separate package, but they are useful, and they may grow up to be full-blown packages one day. That's the reason why they are all namespaced as directly under ActiveCollab namespace, not ActiveCollab\Utils.

What's Inside

1. Class Finder
2. Config Loader
3. Cookies
4. Current Timestamp
5. Encryptor
6. Firewall
7. JSON
8. Value Container
9. URL

Class Finder

ActiveCollab\ClassFinder\ClassFinderInterface - This interface and its implementation provide an easy way to scan directory for classes that extend specified classes, and optional instantination of objects of these classes. It's useful for automatic discovery of command classes in CLI applications, controllers, components, etc.

Config Loader

ActiveCollab\ConfigLoader\ConfigLoaderInterface - Interface specifies a way to load application configuration, while specifying requirements, like option presence, or non-empty value requirements.

Basic Usage

Example below demonstrates basic usage of config loader (we'll use ArrayConfigLoader, but you can use any other config loader implementation):

As example above demonstrates, you can check for presence of option values by calling hasValue(). To get the value of an option, call getValue().

Validators

There are four main validators that can be used to set config option requirements, and let config loader validate if all options that you need are present:

1. requirePresence - Require option presence. Value can be empty,
2. requireValue - Require option presence, and value must not be empty,
3. requirePresenceWhen - Conditional presence requirement; when option X has value Y require presence of option Z,
4. requireValueWhen - Conditional value requirement; when option X has value Y require presence of option Z, and its value must not be empty.

All four validators accept arrays of required fields:

Note: Validators that add conditional requirements will make condition option required, and it's value will not be allowed to be empty.

Validation Errors

In case of a validation error (required option does not exist, or it is empty when value is required), and exception will be thrown:

Note: Requirements can be set prior to calling load() method. If you try to set requirements after config option have been loaded, an exception will be thrown.

Cookies

ActiveCollab\Cookies\CookiesInterface - This interface and its implementation build on top of dflydev-fig-cookies to provide higher level handling of cookies in PHP applications that use PSR-7 messages. Utility class provides a way to check for cookie existence, and to get, set and remove a cookie. Features include:

1. Automatic cookie prefixing,
2. Automatic cookie encryption,
3. Setting cookie's time to live relative to current timestamp,
4. Marking cookies as HTTP only, or secure.

Current Timestamp

ActiveCollab\CurrentTimestamp\CurrentTimestampInterface - Interface specifies a way how to get a current timestamp. Default implementation uses a time() function call, but you can use any implementation, including timestamp locking (great for tests).

Encryptor

ActiveCollab\Encryptor\EncryptorInterface - Interface specifies a way to encrypt and decrypt values. It does not specify how values are encrypted, or decrypted, just that they can be. All dependencies and implementation details need to go to the implementation, and specifics need to be configured via constructor arguments, or setters. Default implementation that uses AES 256 CBC is part of the package.

Firewall

ActiveCollab\Firewall\FirewallInterface - This interface and implementation allow you to check IP addresses against white and black address lists, and block unwanted traffic:

JSON

ActiveCollab\Json\JsonEncoderInterface - This interface and its implementation provide a way to encode JSON in a way that we usually do it, and to test if data is being encoded in tests.

Phone Number

Wrap around libphonenumber to provide phone number value object.

Value Container

ActiveCollab\ValueContainer\ValueContainerInterface - Interface that enables value access abstraction. For example, it can be used to abstract access to a value in a way that class does not know where and how value is store, it just knows that it can check for its presence, get the value, set it or remove it.

Package includes ActiveCollab\ValueContainer\Request\RequestValueContainerInterface. This interface is used when you have PSR-7 request that contains the value as an attribute. Default implementation, that is included with the package, can read and write to the request:

URL

ActiveCollab\Url\UrlInterface - In the current form, implementation of this interface lets you easily add and remove query parameters to a known URL.

How to Add a Utility

1. Add auto-loading code under autoload -> psr-4 in composer.json,
2. Update dependencies with composer update,
3. Implement and test your utility class,
4. Tag and publish a new release.