{"id":24016350,"url":"https://github.com/decodelabs/greenleaf","last_synced_at":"2025-04-15T14:07:31.610Z","repository":{"id":206097773,"uuid":"715776918","full_name":"decodelabs/greenleaf","owner":"decodelabs","description":"Super-fast directory based HTTP router for PHP","archived":false,"fork":false,"pushed_at":"2025-04-14T08:47:47.000Z","size":119,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"develop","last_synced_at":"2025-04-15T14:07:15.733Z","etag":null,"topics":["action","http","middleware","php","psr-15","router"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/decodelabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-07T20:11:23.000Z","updated_at":"2025-04-14T08:47:50.000Z","dependencies_parsed_at":"2023-11-24T23:21:21.163Z","dependency_job_id":"36d96512-3aec-4b12-9e5b-8c830e17c9ae","html_url":"https://github.com/decodelabs/greenleaf","commit_stats":null,"previous_names":["decodelabs/greenleaf"],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decodelabs%2Fgreenleaf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decodelabs%2Fgreenleaf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decodelabs%2Fgreenleaf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decodelabs%2Fgreenleaf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/decodelabs","download_url":"https://codeload.github.com/decodelabs/greenleaf/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249085438,"owners_count":21210267,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["action","http","middleware","php","psr-15","router"],"created_at":"2025-01-08T08:49:01.763Z","updated_at":"2025-04-15T14:07:31.604Z","avatar_url":"https://github.com/decodelabs.png","language":"PHP","readme":"# Greenleaf\n\n[![PHP from Packagist](https://img.shields.io/packagist/php-v/decodelabs/greenleaf?style=flat)](https://packagist.org/packages/decodelabs/greenleaf)\n[![Latest Version](https://img.shields.io/packagist/v/decodelabs/greenleaf.svg?style=flat)](https://packagist.org/packages/decodelabs/greenleaf)\n[![Total Downloads](https://img.shields.io/packagist/dt/decodelabs/greenleaf.svg?style=flat)](https://packagist.org/packages/decodelabs/greenleaf)\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/decodelabs/greenleaf/integrate.yml?branch=develop)](https://github.com/decodelabs/greenleaf/actions/workflows/integrate.yml)\n[![PHPStan](https://img.shields.io/badge/PHPStan-enabled-44CC11.svg?longCache=true\u0026style=flat)](https://github.com/phpstan/phpstan)\n[![License](https://img.shields.io/packagist/l/decodelabs/greenleaf?style=flat)](https://packagist.org/packages/decodelabs/greenleaf)\n\n### Super-fast directory based HTTP router\n\nGreenleaf provides a fast and flexible way to route HTTP requests to your actions and pages.\n\n---\n\n## Installation\n\nInstall via Composer:\n\n```bash\ncomposer require decodelabs/greenleaf\n```\n\n## Usage\n\nThe main entry point to use Greenleaf is a PSR-15 middleware that can be used with any PSR-15 compatible framework, such as [Harvest](https://github.com/decodelabs/harvest). It will parse the request and attempt to match it against a set of configured routes.\n\nThe system is comprised of a set of generators that can scan and find available routes, a collection of flexible route types and an extensible dispatcher architecture that allows for different matching strategies.\n\n### Dispatcher\n\nWhile the dispatcher is usually accessed through middleware, you can if needed instantiate the Dispatcher directly and treat it as a standard PSR HTTP Handler.\n\n```php\nuse DecodeLabs\\Greenleaf;\nuse DecodeLabs\\Harvest;\n\n$dispatcher = Greenleaf::createDispatcher();\n$request = Harvest::createRequestFromEnvironment();\n$response = $dispatcher-\u003ehandle($request);\n```\n\n### Namespace\n\nThe router will use [Archetype](https://github.com/decodelabs/archetype) to resolve Action classes from the URL - you can use Archetype's namespace mapping functionality to mount a directory for Http related classes:\n\n```php\nuse DecodeLabs\\Archetype;\nuse MyApp\\Http;\n\nArchetype::alias('DecodeLabs\\\\Greenleaf\\\\*', Http::class);\n```\n\nIf your app is based on the [Fabric](https://github.com/decodelabs/fabric) framework, this mapping is taken care of for you automatically, based on the app namespace in your config.\n\n### Generators\n\nGenerators are used to load and configure routes. The `Generator` interface defines a simple mechanism for implementations to find and load routes.\n\nBy default, Greenleaf will load a `Scanner` Generator which in turn will scan the directory tree for other Generators and load the Actions they provide.\n\nTo define Routes in your directory tree, you can start with a generic `Routes` Generator which expects routes to be defined by hand:\n\n\n```php\nnamespace MyApp\\Http;\n\nuse DecodeLabs\\Greenleaf;\nuse DecodeLabs\\Greenleaf\\Generator;\nuse DecodeLabs\\Greenleaf\\GeneratorTrait;\n\nclass Routes implements Generator\n{\n    use GeneratorTrait;\n\n    public function generateRoutes(): iterable\n    {\n        // Basic route\n        yield Greenleaf::action('/', 'home');\n\n        // Basic route with parameter\n        yield Greenleaf::action('test/{slug}', 'test')\n\n        // Route with inset parameters\n        yield Greenleaf::action('test-{slug}/', 'test?hello')\n            -\u003ewith('slug', validate: 'slug');\n\n        // Route with multi-part path parameters\n        yield Greenleaf::action('assets/{path}', 'assets')\n            -\u003ewith('path', validate: 'path');\n\n        // Redirect\n        yield Greenleaf::redirect('old/path', 'new/path');\n    }\n}\n```\n\n\n### Router\n\nWhen the Dispatcher runs, it loads an appropriate `Router` to take care of matching the request to the configured routes.\n\n_At this moment in time, Greenleaf contains a reference Matching implementation that just brute forces its way through the list of routes until it finds a match. This implementation is not optimised for speed and will be replaced with a high performance compiled router system that will be able to handle thousands of routes with ease._\n\nWhen a Router implementation finds a match, it transforms the route pattern into a custom \"leaf URL\" in the format `leaf:/path/to/file` and a set of parameters that are then passed to the target of the route.\n\nThis is one of Greenleaf's biggest strengths as both input and output forms resolve to URL formats that can be easily looked up and matched against, both when matching _in_ and when generating _out_.\n\n### Leaf URL\n\nThe URL format is mostly just a subset of HTTP URLs, with `leaf` as the scheme, standard path, query and fragment components.\n\nFor example:\n\n```php\n// Route\nGreenleaf::action('test/{slug}', 'test?hello');\n\n// Creates URI\nGreenleaf::uri('leaf:/test?hello');\n// $parameters = ['slug' =\u003e 'value-of-slug-in-request']\n\n// Resolves to:\n$actionClass = MyApp\\Http\\Test::class;\n\n// --------------------------\n// Or\nGreenleaf::action('blog/articles', 'blog/articles');\n\n// Creates URI\nGreenleaf::uri('leaf:/blog/articles');\n\n// Resolves to:\n$actionClass = MyApp\\Http\\Blog\\Articles::class;\n```\n\n### Routes\n\nThere are currently three types of route available in Greenleaf:\n\n- **Action**: A route that maps to an Action class. The action must implement the `DecodeLabs\\Greenleaf\\Action` interface and provides the most flexibility in responding to requests\n- **Page**: A route that maps to page components, in the same vein as the likes of Next.js. `PageAction` adapters handle loading different types of page content\n- **Redirect**: A route that redirects the request to a different URL. This is useful for handling legacy URLs or for redirecting to a different domain\n\n\n#### Action\n\nActions need to implement an `execute(DecodeLabs\\Greenleaf\\Request $request)` method, and return a Response. Greenleaf provides a number of traits that can be used to add additional functionality and simplify writing logic for your views.\n\nThe `ByMethodTrait` for example will attempt to invoke a method on the Action based on the HTTP method of the request.\n\nNote that most traits that work in this fashion will use `Slingshot` to invoke the method with deep dependency injection support. In this example, the slug from the matched route request URL is passed as a string to the action handlers.\n\n```php\nnamespace MyApp\\Http;\n\nuse DecodeLabs\\Harvest;\nuse DecodeLabs\\Harvest\\Response;\nuse DecodeLabs\\Greenleaf;\nuse DecodeLabs\\Greenleaf\\Action;\nuse DecodeLabs\\Greenleaf\\Action\\ByMethodTrait;\n\nclass Test implements Action\n{\n    use ByMethodTrait;\n\n    public function get(\n        string $slug\n    ): Response {\n        return Harvest::text('Get response');\n    }\n\n    public function post(\n        string $slug\n    ): Response {\n        return Harvest::text('Post response');\n    }\n}\n```\n\nActions don't necessarily need to return PSR-7 responses directly - Greenleaf uses [Harvest's](https://github.com/decodelabs/harvest) response transformation system to convert all types of content responses to full PSR-7 HTTP responses.\n\n\n#### Page\n\nA page route is usually resolved to a content file or other type of component. Greenleaf provides a basic HTML file adapter that will load a file from the filesystem and return it as a response, however other packages provide more complex implementations, such as [Horizon](https://github.com/decodelabs/horizon) `Page` and `Fragment` component structures.\n\nWhen a page route is matched, the file path is resolved using [Monarch's](https://github.com/decodelabs/monarch) path alias system, from a base path of `@pages`. This alias if not defined by your app, defaults to the `@run/src/components/pages` directory.\n\n```php\n...\n\n// HTML file /src/components/pages/about.html\nyield Greenleaf::page('about', 'about.html');\n\n// Horizon Page /src/components/pages/blog.php\nyield Greenleaf::page('blog', 'blog.php');\n\n// Set default component type\nGreenleaf::setDefaultPageType('php');\n\n// Same as above\nyield Greenleaf::page('blog');\n```\n\n### HTTP URLs\n\nOne of the main benefits of Greenleaf is that it allows you to generate URLs for your routes in a simple and flexible way by creating leaf URLs with many of the required URL constructs already in place.\n\nThe router will then be able to match these URLs to the correct route and pass the parameters to the HTTP URL generator.\n\n```php\nuse DecodeLabs\\Greenleaf;\n\n// route pattern: test/{slug}\n\n$url = Greenleaf::createUrl(\n    'test?hello#fragment',\n    ['slug' =\u003e 'my-slug']\n);\n\n// https://mydomain.localtest.me/test/my-slug?hello#fragment\n```\n\n## Licensing\n\nGreenleaf is licensed under the MIT License. See [LICENSE](./LICENSE) for the full license text.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdecodelabs%2Fgreenleaf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdecodelabs%2Fgreenleaf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdecodelabs%2Fgreenleaf/lists"}