Download the PHP package rosengate/sigil without Composer

Sigil

Laravel-Exedra PHP 8 attributes based routing controller package

Table of Contents

• Features
• Requirements
• Setup
• Basic Usages
• Routing Conventions
• Routing Attributes
• Sub-routing / Group
• Middlewares
  • Global middlewares
  • Group based middlewares
  • Method based middlewares
• Meta Information
  • State
  • Series
  • Flag
  • Usages of Meta Information
  • Make your own attributes
• DI Method Injection
• Utilities
  • Route Model
  • PHPLeague Transformer
  • Renderer
• Console Commands
• Todos
• Drawbacks
• Feedbacks
• Why
• License

Features

• Couple your routing with the controller class
• PHP 8 attributes based routing component
• Nested routing
• Provide a flexible ways to control/design your application through means like :
  • sub-routing based middleware
  • meta information
  • create your own attributes, and control it through your own middleware

Requirements

• Laravel
• PHP >= 8
• this packages overrides your laravel Http Kernel and wholly use routing/controller/middleware component from rosengate/exedra, however it still fallbacks to laravel routes when there's no matching routes.

Setup

1. Install package through composer

For Laravel 10 and below

For laravel 11 onwards

2. Register Sigil\SigilProvider

For Laravel 10 and below

Register Sigil\Providers\SigilProvider inside your config\app.php

For Laravel 11 onwards, you can register this under bootstrap/providers.php

3. publish and cache the config

Run vendor:publish

Config cache

4. Http Kernel Extension

Since this package interact changes at http level, sigil does it's own bridging through Laravel Http Kernel.

For laravel 10 and below, extend your App\Http\Kernel with Sigil\SigilKernel (as this package uses it's own routing and request dispatch).

For Laravel 11 onwards, you may go to your bootstrap/app.php and replace Application with Sigil\SigilApplication. This replacement handles Kernel extension on it's own.

Basic Usages

Provided with your installation is the root controller where you'd define your initial routing.

The second controller WebController would be the front facing controller for your app (following laravel similar routing)

Routing Conventions

The routing registry through the controller is built upon conventions and prefix through method name.

Create an action only for particular (REST) methods

• get(), post(), delete(), patch(), put()
• can also suffix with additional string for eg. getUsers()

Create an action for any methods

• prefix with execute WITH additional string
  • for eg. executeContactUs()

Create a method based middleware

• middleware or middlewareAuth

Examples

Create a routing group

Nest a routing

• prefix with group WITH additional string
  • for eg. groupBook

Examples

Routing setup

• if you prefer a more programmatically routing, you can create a setup(Group $router) method.

Routing Attributes

• Path(string path) define the path for the current route / routing group (relatively)
• Method(string method|array methods) set method accessibility
• Name(string name) set route name
• Tag(string tag) tag the current route
• Middleware(string middlewareClass) add middleware
• State(string key, mixed value) a mutable meta information
• Series(string key, mixed value) an additive meta information
• Flag(mixed flag) an array of meta information
• Requestable(bool) set whether this route is requestable or not
• AsFailRoute mark the selected route as fallback route

Sub-routing / Group

This package allows you nest your routing beneath another routing indefinitely. Your routing uri/path is relative as it goes down the depth.

Create a method with the name prefixed with group, and return the name of the controller.

The routing will give a result like :

Middlewares

Feel free to use your laravel middlewares at it still follows the same signature, and the constructor arguments are also injected with laravel di container.

Global middlewares

If you follow the SigilSetup above (by providing the array of middleware classes), you'll just need to maintain your list of middleware in your App\Http\Kernel $middleware property.

Group/route based middlewares

A class based middlewares.

Method based middleware

You can make a middleware directly in the controller itself by prefixing the method name with middleware. While doing so, you can also inject any registered instance through the method arguments.

This method gives you more control over the context of the current routing through the use of middleware.

Meta Information

The nested nature of this framework allows us to design our app as flexible as we wish. However, there are three types of information we can use for this purpose.

State

A mutable key based information.

Series

An additive / array based key specific information. New information is appended instead of mutated.

Flag

An array of flags / information. Similiar to series, but more simpler.

Usages of Meta Information

Meta information are best used with a middleware where you could control the flow/behaviour/design of your application by your defined metas.

For eg, let's use some of the meta information we wrote above and write some pseudo codes.

Make your own attributes

The simplest way to create your own attribute is by extending these meta information and use them on your own terms.

For eg. we want to have an attribute that determine which routing goes to which user roles.

Create a middleware to utilize this information.

Then add this middleware in your App\Http\Kernel

Now you can use this attribute in any of your controller.

DI Method Injection

The DI wiring of this package make use of laravel container registry. So, anything that you registered on app() container can also be retrieved here.

For eg :

Utilities

Route-Model finder / registry

Example usages

Handling exception

You can handle model not found exception by simply creating a middleware that catch such exception.

For eg.

PHPLeague Transformer

PHP League Fractal transformer. Transform your api response from your laravel model/collection by annotating your action with . This package uses spatie/laravel-fractal.

Usage

Renderer

Handle the content returns of your controller action by defining a renderer that implements Sigil\Contracts\Renderer.

Setup

Console Commands

List routes

List all routes

Filter routes under web. routing

Todos

• laravel url generator compatibility
• better installation / setup procedure
• related artisan commands
  • route list
  • make controller
• Caching strategy / testing
• More stable release

Drawbacks

~~As this package completely use a different component for routing, in general it will be incompatible with any other packages that make use of laravel routing or the routes folder. Also these components as of now :~~ - Url Generator - Redirection with route name As of now, this package will still fallback to laravel routing when there're no matching routes.

Why

I wrote rosengate/exedra back 4 years ago because i couldn't find a framework that can exactly do what I wanted, like hierarchically nest a routing beneath another routing. Also exedra was never meant to be another full-fledged framework. It's just a microframework and I always advocate for the use of tons of amazing php packages out there. Then I built a phpdoc based routing controller component and since then writing a code with exedra became a bliss than ever. But building things from microframework can be daunting as I always needed an ORM, validation, error handling, and many other tools out there (I always find myself using Elqouent).

Then at one point I became so used with laravel and decided to try it with exedra. I was starting to think that this is kinda possible. Then PHP8 came with a news so good I've been waiting for years. Attributes/Annotation. So I decided to just port it for laravel and see how it goes here. <3

Feedbacks

• Feel free to throw in feedbacks through github issues. - I am planning to find a way to integrate with Illuminate\Contracts\Routing\UrlGenerator soon.

License

MIT License