sageit/phalcon-micro-annotations

Sage IT Component for Phalcon - Annotations Parser for annotation routes

v1.00 2022-12-28 16:48 UTC

Requires

• php: >=7.0
• ext-phalcon: 4.* || 5.*

Requires (Dev)

• codeception/verify: *

MIT

• Daniel S. Davis

• framework
• micro
• annotation
• phalcon

README

Phalcon Micro-Annotation

Allows you to use annotations for routing on Phalcon Micro Applications. While the built in Phalcon class for an annotation based router works on full suite Phalcon apps, Micro uses a different mounting methodology and does not support this. The Micro-Annotation Router leverages the build in Micro mounting method while allowing for annotation parsing with the caching method of your choice.

Explore the docs »

Report Bug · Request Feature

Table of Contents

• About the Project
• Installation
• Usage
• Caching
• Roadmap
• Contributing
• License
• Contact
• Acknowledgements

About The Project

Built With

• vscode
• php 8.1.1
• Phalcon 5 (Micro Framework)

Installation

Git:

git clone https://github.com/SageITSolutions/phalcon-micro-annotations.git

Composer:

composer require sageit/phalcon-micro-annotations

Usage

This project consists of an included Router class extension which follows closely to the Phalcon 5 Namespace convention. Once a service is added in the micro app, this can easily be leveraged.

Create a Service (Example)

namespace App\Service;

class Router implements \Phalcon\Di\ServiceProviderInterface
{

    public function register(\Phalcon\Di\DiInterface $di): void
    {
        $di->setShared(
            'router',
            function () use ($di) {
                return new \Phalcon\Mvc\Router\Annotations\MicroRouter($di, (object) [
                    "adapter" => "apcu",
                    "directory" => "app/controllers/",
                    "namespace" => "App\Controllers",
                    "lifetime" => 21600000,
                    "cachedirectory" => "/app/storage/cache/annotations/"
                ]);
            }
        );
    }
}

When creating the service, MicroRouter requires 2 parameters.

1. The Dependancy Injector the service is added to.
2. An Object containing optional settings.

The provided example demonstrates the default values assumed if the option is ommited.

Mount Micro to the service

From within the Micro class call:

$this->getDI()->get('router')->mountMicro($this);

this will pass the micro app ($this) to the parsor and call the micro mount method using the parsed annotions

Caching

This class supports safeguarded Caching. You can choose between APCu, Stream, or Memory (Not Caching) when creating the router service to optimize usage.

Specifying Cache Method

Within the Options array passed to the MicroRouter, specify the adapter of choice.

APCu

"adapter" => "apcu",
"lifetime" => 21600000,

APCu

"adapter" => "stream",
"cachedirectory" => "/app/storage/cache/annotations/"

Memory

"adapter" => "memory"

technically, Memory is the fallback when all others fail, so any value not APCU or Stream would resolve to memory

Safeguards

Once specified, the class checks for the presence of the required components before using a caching method. This works in a tiered manner.

1. APCu is specified, checks are made if APCu is installed and enabled, if not the adapter will revert to Stream
2. Stream is specified (or APCu specification failed), checks are made that the directory specified for cachedirectory exists, if not adapter will revert to Memory
3. Memory is specified (or result of reverting), no checks are required, all parsing is done in memory each time.

Parsing

When caching methods are enabled, they are processed first before iterating files producing I/O calls. If annotations are present, no files are parsed, and routes are generated from memory. When no annotations are present (first call or after clearing cache) then Controller files are parsed from the provided directory and annotations are added.

Clearing Cache

A public utility method is included to facilitate the need to rebuild the cache either in testing or publishing scenarios. Clearing Cache is dependant on the adapter specified.

clearCache()

From within the micro class

$this->getDI()->get('router')->clearCache();

This will remove all APCu entries with the prefix _phan or removing all files in the cachedirectory depending on the adaptor type.

if the dependancy injector identifies as logger service, the notices are logged indicating the cleared cache

Roadmap

See the open issues for a list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Sage IT Solutions - Email

Project Link: https://github.com/SageITSolutions/phalcon-micro-annotations

Acknowledgements

• OakBehringer