Command api finalized

feat(command): finalizing command api, using ini files by default ins…

…tead of yaml (this means the yaml extension is no longer required for a basic program).

Catpaw V3

Breaking Changes

• The Unsafe api has changed.
  Previously invoking Unsafe::try($error) would get the value of the object and possibly assign the error by reference to $error.
  This method has been renamed to Unsafe::uwnrap($error), which does the same exact thing.
  The old Unsafe::try(), still exists, but it now serves a different purpose: it still gets the value of the object, but it now throws the error instead of assigning it to an external variable.
  The error management section has been updated, you can read more about these changes there.

• The Server api now uses a fluent api.
  The router section has been updated, you can read more about these changes there.

New features

• Introducing Superstyle!
  A new way of writing markup documents by describing the DOM using only CSS.
  You can read more about Superstyle here.

• The catpaw.phar bundle now offers a baked in pre-commit feature.
  You can use it to execute custom commands before committing, like running tests, formatting, linting etc.
  The project starters come with a composer script dev:install-pre-commit which you can run to automatically setup your pre-commit hook.\

  You can also manually setup the pre-commit hook with the --install-pre-commit option

  php catpaw.phar --install-pre-commit="composer prod:test"

  whatever string you pass in will be executed as a command before committing.\

  And of course you can uninstall the current pre-commit hook with --uninstall-pre-commit

  php catpaw.phar --uninstall-pre-commit

Misc

Previously type safety was a bit relaxed due to some issues and frustrations with psalm during development.
The whole project is now type safe and it uses phpstan for static analysis.

File, Directory apis streamlined & Container providers

File, Directory apis streamlined & Container providers

Changes

• All methods of both File and Directory classes no longer return Futures.
  The Futures are instead resolved internally.

• The Container can now set providers through Container::provide()

  /**
   * Set a provider or a singleton.
   * @param  string          $name
   * @param  callable|object $value The value to set.\
   *                                If the `$value` is a `callable` then the container treats it as a provider, 
   *                                otherwise it treats it as a cached singleton.
   * @return void
   */
  public static function provide(string $name, callable|object $value):void;

  For example

  Container::provide(MyCustomClass::class, fn () => new MyCustomClass($arg1, $arg2));

  Your provider function can also expect parameters, which you can pass down through Container::create.

  /**
   * Create an instance or retrieve a cached instance of the given class.
   * - This method will take care of dependency injections.
   * - Services and Singletons are backed by an internal cache, which you can reset by invoking `Container::clear()`.
   * - Providers' results are not cached.
   * @template T
   * @param  string    $name
   * @param  mixed     $args
   * @return Unsafe<T>
   */
  public static function create(string $name, ...$args):Unsafe;

• The old Container::set method is now deprecated in favor of Container::provide.

Goffi & FileName

Changes

• Removing asPharFileName which had been briefly introduced to manage file names within the phar archive.
• GoffiContract no longer converts file names to phar file names when in phar mode.
  Use the new asFileName()->withPhar() solution instead.
• asFileName no longer returns a string, instead it will return a CatPaw\Core\FileName, which implements Stringable, making the change backward compatible.
  The new FileName class offers a ->withPhar() method.
  This method will detect if the given file name is present in your .phar file first, if not, then the file name will fallback and try to find the file name in your file system.

When you run the following code

<?php
use function CatPaw\Core\asFilename;

function main(){
   echo asFileName(__DIR__, 'main.php')->withPhar().PHP_EOL;
}

with

composer prod:start

it will print the file name found on your file system

/home/raz/Desktop/starter/src/main.php

On the other hand, if you build it to a .phar and then run it

composer prod:build &&\
php app.phar

it will print the file name found in your .phar

phar:///home/raz/Desktop/starter/app.phar/src/main.php

Native Gui & Go FFI finalized

Changes

• Adding some primitives for native gui support, read more here.

• Goffi feature finalized and adding support for Goffi in phar mode, aka you can run composer prod:build and it will work.
  This is achieved by dumping the shared objects and header files in the current directory.

• Adding a new function asPharFileName() which takes care of converting a given file name into a file name relative to the archive.

  <?php
  use function CatPaw\Core\asPharFileName;
  
  function main() {
      echo asPharFileName("./src/main.php").PHP_EOL;
  }

  When running with

  composer prod:start

  the program will print /home/raz/Desktop/starter/src/main.php.

  Whereas when running with

  composer prod:build &&\
  php app.phar

  the program will print phar:///home/raz/Desktop/starter/app.phar/src/main.php.

Goffi strings

Changes

• GoffiContract will not require interfaces to specify Unsafe return types.
• GoffiContract will now automatically resolve C strings returned from Go according to the given Php interface, read more here.

Goffi & Signals

Changes

• Adding experimental FFI api with Go, read more here.
• Completing the signals api, read more here.

Fixing builder

Changes

• Fixing an issue where the builder would inject the wrong default environment file

Better environment detection

Changes

• Better environment detection
• Adding --hi option, which will respond with hello.
  A quick mechanism to make sure the binary works.
  A proper --help will be added in the future.

Better phpdocs and adding attributes flags

Changes

• Improving phpdocs and project docs in general
• Adding flags to existing attributes