Download the PHP package spaf/simputils without Composer

:ukraine: #StandWithUkraine

This is the official Bank of Ukraine link for donations for Ukraine:

https://bank.gov.ua/en/news/all/natsionalniy-bank-vidkriv-spetsrahunok-dlya-zboru-koshtiv-na-potrebi-armiyi

SimpUtils

Those badges are outdated for now :(

SimpUtils is a micro-framework that provides really simple and lightweight tools for development and prototyping. Additionally, there are tools for comfortable and efficient optimization and debugging.

The framework does not have much of composer dependencies (on purpose), to make sure that it does not bloat your vendor folder.

The main purpose of the framework is to improve development experience, and it does not oppose any of the popular framework giants like "Yii2/3", "Laravel" or "Zend". The SimpUtils can be easily used in combination of any framework.

The framework extends PHP language with some useful perks. Provides similar to native classes, but improves their capabilities. Normalizes naming and architecture.

All the aspects of the framework were designed to improve code development and readability. All the components and features are designed to be intuitive and transparent for common use cases, but really flexible in case of need.

P.S. The framework I develop for my own projects, but I'm really happy to share it with anyone who is interested in it. Feel free to participate! Suggestions, bug-reports. I will be really happy hearing from you.

License is "MIT"

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Changelog

Changelog

Important notes

1. Currently, JSON serialization and deserialization does not work properly. Please do not rely on it for now! IMPORTANT! When fix for this problem comes, and you are using current logic - you might get into a broken code logic. Please do not use \spaf\simputils\PHP::serialize() and \spaf\simputils\PHP::deserialize() code with JSON mechanics, you can switch the mechanics to native PHP like this (workaround):

   That will use native PHP mechanics for serialization, which should work properly starting from this release (1.1.3)

Documentation

Important note about the documentation: Due to urgent need of the stable release, I had to strip out all the documentation (it was really outdated because of my architecture revisions). So please, wait just a bit, with patches after the stable release I will provide more documentation. The very first stable release must be polished in matter of architecture, so documentation will come after that in the very nearest time. My apologies.

Some:

1. Glossary
2. Structure
3. Important notes - this can help with troubleshooting

Installation

Minimal PHP version: 8.0

Current framework version: 1.1.6

Keep in mind that the library development suppose to follow the semantic versioning, so the functionality within the same major version - should be backward-compatible (Except cases of bugs and some rare issues).

More about semantic versioning: Semantic Versioning Explanation.

"dev-main" Stable version

From this point, I decided to have stable version with some recent updates that I need before the final release. Consider it "ALPHA" release.

Though, avoid using it on production, it would be times better if you would just poke me with a ticket, so I would release the stable version quicker!

Just keep in mind, even though it should be stable, it's still "unreleased" and might be even unfinished concepts. Please avoid using it without serious reasons.

Important: DO NOT USE THIS VERSION, IF YOU ARE NOT SURE WHAT IT DOES. For production always use the installation method above!

All the features of this branch will be properly packaged and released, don't worry about that!

"dev-dev" Unstable version

Additionally, I've decided to have unstable version with much more recent updates that I need in a first row with unfinished and broken concepts.

Just keep in mind, it can completely break your code, unfinished concepts or even broken code could be here very common thing.

I strongly recommend to avoid using this code, except cases when you are very totally sure what you are doing!

Important: DO NOT USE THIS VERSION, IF YOU ARE NOT SURE WHAT IT DOES.

All the features of this branch will be properly packaged and released, don't worry about that!

Quick highlights and examples

Just a few tini-tiny examples of very condensed functionality :)

1. Renderers
2. Working with URLs
3. Data files and executable files processing
4. Properties
5. Date Times
6. Advanced PHP Info Object
7. IPv4 model
8. Path-alike Box-array
9. Stretchable feature of Box-array (paramsAlike())
10. "with" love

Working with URLs

The new feature of "URL" object (UrlObject) has arrived and almost finished. After recent update it's tested enough to be considered stable (even though some unconventional cases of bugs can still occur).

Example:

Output would be:

It can not only generate, but parse as well and even combine parts:

Output would be:

And after all that you could get parts separately and play around with them.

For example, we get "path" parts, and they are returned as a Box-array, you can work with them sequentially, but as soon as you stringify them, they turn back to "path" string again:

The output would be:

Another moment worth mentioning, that when you modify the "path" box object - it will affect the url object as well. (if you want to avoid that, always clone the object instead)

The same example as above, but outputting the whole url object now:

Output would be:

All of the above work similar to params.

Important: For string arguments, full parsing happening only for $host parameter, additional path (+params+sharpy) parsing happening for $path (uri) parameter, and $params does not do the "string-parsing". String is not allowed as data type for $params argument (at least for now).

Current page / Active Url

New method prepared for getting the current Url (works only for web, will not work for CLI without faking some params):

Output might depend on your web-server:

This allows to identify if the $url object is Current Url or Active Url:

The output might depend on your web-server:

There are nice parameters of UrlObject::isCurrent() that could be tweaked. Besides that there is another comparison method for 2 different urls, and not only the current web-page url UrlObject::isSimilar(), structure of which is almost the same.

SOME FEATURES ARE NOT FULLY IMPLEMENTED

• url extension like a "russian-nesting doll"
• "params" parameter parsing strings
• Support for other protocols except HTTP(S)
• maybe something else as well!

Files, Data Files and executables processing

Files Infrastructure

Working with files can be really easy:

IMPORTANT: "content" read or write DOES REAL READING/WRITING EVERY SINGLE CALL! So please if you need to use it multiple times in code - please store it in a var

The output would be:

Cool feature is to have ram files without real HD file created, and then moved/saved from the RAM to the HD file-system.

P.S. Currently there is no explicit property to tell which file is RAM and which is HD, but this feature should appear in the future releases.

In the example above there is a simple textual data is used. The processing capabilities depend on the Resource App Processor and can be customized in any way you want.

Currently, there are a few of them:

• \spaf\simputils\models\files\apps\CsvProcessor - CSV file processing
• \spaf\simputils\models\files\apps\DotEnvProcessor - ".env" file processing
• \spaf\simputils\models\files\apps\JsonProcessor - JSON files processing
• \spaf\simputils\models\files\apps\TextProcessor - Default used for any non-recognized file types
• \spaf\simputils\models\files\apps\PHPFileProcessor - Special processor, it is not allowed to be use directly for security reasons!

By default, if file is not recognized then TextProcessor is used.

The processor can be used explicitly when creating file object or can be re-assigned later:

It's really nice way to work with files, when the processing/parsing/generation of the content of the file depends on the app.

P.S. Found a tiny bug in using one file object for different file types, please avoid for now changing file type. https://github.com/PandaHugMonster/php-simputils/issues/124

Please do not use PHPFileProcessor. It's a really special processor, which is used in some rare cases across the framework. But it should never be explicitly used. Do not override it

Files App Processors can be set as default by "mime-types" as well, instead of explicit specification of each object with the exact Resource App Processor.

Important: PHP::redef(File::class) is an easy way to refer to the File class, it is safer than using just a File class directly, because in your system you might redefine some models/classes - and then in this case you might break compatibility. The PHP::redef(File::class) is used to avoid such a problem.

Additionally: The text/plain mime-type is the default one for unspecified cases. So if you redefine it, any unspecified/unrecognized files will be using it!

You can redefine the complete set of supported mime-types. And even create your own.

Data Files

Data Files are scoped set of files with configs or some stored info in files for your application.

It's a common thing to want to save a small config into JSON or "PHP-Array" files, and then read them and use.

Or store some test-fixture or dictionary data for DB migrations.

All of that is easily achievable through Data Files.

To use data files you need to specify permitted folders from which those files will be used. Without specifying those directories - files will not be accessible as "Data Files".

Keep in mind that the data is retrieved through the Files infrastructure. This is why you could alternatively could use directly through "File" objects.

The output would be exactly the same.

It's recommended to use FS::data() over FS::dataFile().

Executables Processing

Files Infrastructure is not supposed to be used to execute "PHP" files (except through Data Files).

So the following code:

and

Both above code cases will cause exception:

This behaviour is very intended due to security reasons! Do not try to override this behaviour.

Special notes

1. For every PHP::init() process the ".env" file is searched and processed, so it's easy to specify/modify env variables. The values are accessible through env() function. In case if you want to disable it:

2. ALL THE ENV VARS MUST BE REFERRED IN UPPER CASE!!! So if you have the .env vars like this: "test_1" - then in env('TEST_1') always use the UPPER CASE! It's mandatory due to best practices.

Properties

The output will be:

Important: Ignore some additional fields like "_orig_value" and "_simp_utils_property_batch_storage" in DateTime object, it's due to really nasty bug of the PHP engine, that seems to be really ignored by the PHP engine developers.

Cool way to hide some fields from the debug output with special attribute DebugHide:

And the output will be:

Date Times

Simple quick iterations over the date period

Using prisms Date and Time:

Both prisms of Date and Time work for any of the DateTime simputils objects.

All this math is done natively in PHP, so it's functionality native to PHP. The overall usage was partially improved, so it could be chained and comfortably output.

All the object modification can be achieved through modify() method as well (add() and sub() works in a very similar way). Here you can read more about that: https://www.php.net/manual/en/datetime.modify.php

Examples of getting difference between 2 dates/times

What if you want to get difference for all those modifications? In general you could use the following approach:

But example above is a bit chunky, it would be slightly more elegant to do the following:

Important: All the changes are accumulative, because they call $this->snapshotOrigValue(false) with false first argument. If you call that method without argument or with true - it will override the condition with the current one.

Example of DatePeriod

Example of DateInterval

Suggested to always use SimpUtils versions of DateTime related classes.

Advanced PHP Info Object

Everything is really simple with it. It's an array-like (box-like) object that contains almost complete PHP Info data. That you can access and walk through any comfortable for you way. It also compatible with the common IDE autocomplete (only top level fields).

You can access top-level fields (those that directly on the object):

1. In a property/field-like style:

2. In an array-like style (box functionality is also available):

3. Iterate over the object:

Additional benefits

1. All the versions are wrapped into Version class (out of the box version comparison, etc.)
2. The object is created once, and can be accessed through PHP::info() (manually possible to have multiple)
3. The object is being derivative from Box, that means that it has all the benefits ( all the underlying arrays are Boxed as well, so the whole content of the php info is available through Box functionality)
4. Contains lots of information, and probably will be extended in the future with more relevant information.

Reasoning to use Advanced PHP Info Object

The native phpinfo() returns just a static text representation, which is incredibly uncomfortable to use. Info about native one you can find here: https://www.php.net/manual/ru/function.phpinfo.php

IPv4 model

Simple example:

The output would be:

Path-alike Box-array

This is a new feature for Box model.

The new short version Box::pathAlike() method is available:

Output would be:

Here is the manual way with different examples:

The output would be:

Stretchable feature of Box-array

It works almost exactly as "Path-Alike", but it stringifies boxes including "keys".

Example 1:

Output would be:

And as it might be obvious already, there is a really good potential to use it for url params.

Example 2:

Output would be:

Important to note, this methods does not turn the objects directly to strings! They store in the object special configuration, that when you start to stringify this Box - it will use the saved settings for that.

Value wrappers and htmlAttrAlike()

For html attrs alike just use this method:

Output would be:

But if you would want to do "value-processing" instead of just wrapping, you could use stretched functionality:

Output would be:

Wrap, wrap, wrap

For stretching functionality you can wrap each part separately with $value_wrap and $key_wrap. They work in the same way, but wrap their each corresponding part. After that or instead of that if for the $stretcher argument provided the function/callable/closure then it will be used for wrapping the whole pair.

Keep in mind, that if you specify wrappers for key or value they already will be applied before the stretcher callable is called!

Example bellow will help to understand the logic.

Output would be:

"with" love

Python specific command with can be easily implemented through meta-magic and callables.

Simple example:

You can access the target object easily from the callable:

The example above can be combined if you want to use more from the outer scope, but to keep the elegant way :)

The syntax obviously is not that cute as in python, but functionally it's the same thing.

P.S. Keep in mind that the with() functionality relies on "MetaMagic" trait, and object should use either the trait or implement 2 methods of ___withStart() and ___withEnd()

Really important to note - all above is really minimal description, basically a tip of the iceberg! There are lots of useful functionality description will be added in upcoming weeks.

Additional composer scripts

You can test and analyze code with some additional scripts in composer.

List all available scripts:

Output something like:

Automated Testing and Coverage

Testing

Requires PHPUnit, php-mbstring, php-xdebug, php-bcmath (GMP extension will not work. It has loss of precision, so some tests will fail)

For APT-GET compatible OS those could be installed like this:

Running tests

Code Coverage

Requires PHPUnit

Mess Analysis

Requires phpmd