Download the PHP package hacp0012/quest without Composer

Quest

Access resources directly without defining routes, thanks to PHP attributes.

Please visite online doc

▶️ French Readme here

• Introduction
• Instalation
• Usage
  • The service container
• Runnig operation
• API reference
• FAQ

🪬Introdiction

Quest, the Master Guru which simplifies your quest, it gives you a short route to follow to reach your goal (resource).

I know, you don't need to lie to me 🤥, you have remembered when you are brainstorming to implement a functionality or recover resources and ask you: but ... how do I will organize my Routes?

The question of the routes, I do not hide you, me, it fucks the laziness. Because I must be defined a road for any call and suddenly I find myself with many of the defined Routes.

I know, it's not perfect, and neither is Quest, but... it will make your job a lot easier and eliminates all that mental overload, useful but boring.

✨ Installation

Prerequisites

• PHP 8.0+
• Laravel 9.x+
• Have already made use of the Facade Route. Ex: Route::get('route/to/x/{param}', fn(string $param) => X)

Install Quest from composer

Publish the config files

Quest needs a few files to work properly.

The file route quest.php

is a base file that can be useful to you to register your classes. Because the classes registered in this list are public of the second level, because they have a priority that comes after the list passed in your route Quest:spaw(routes: [])

These references are accessible from all requests.

Experimental: It is now possible to pass directories, whose base starts from the base directory (of the project) of Laraval. Very useful if you do not want to specify each time a class that contains your references, You just have to specify a directory or several directories.

Provided that the punched method is in a class and the class is in a namespace. Only the first class is considered in a .php file.

This file is generated automatically but you can generate it manually.

The config quest.php

Contains some settings you can apply if you have made patterns in your project's bootstrap/provider.php for custom targeting of your route files (/routes/web.php or /routes/api.php).

Because Reference Tracker needs to know your targets to track your referenced (punched) methods.

To publish the configuration files type the command php artisan vendor:publish

This will create the file config/quest.php (which contains some configuration bits) and the global quest routing file in routes/quest.php.

Manually, you can publish the config files like this php artisan quest:publish in the configs/ and routes/ directory manually.

🏳️ How is it useful to me?

Quest allows you to access resources or send your resources directly without worrying about Routes. You just need to set Reference Flags or Reference Marks using PHP attributes on your class methods and call 🤙 these methods directly, with the same parameters as those of the method.

Don't worry, you just need to respect the same types of parameters that you had defined on your method.

Let's take for example, in a case where you are designing an application and reach a certain level where your application will need to retrieve an up-to-date list of telephone codes. You just have to create a method in a class, reference it and call it; without worrying about creating a route for it.

An other exemple :

Note that Quest takes care of passing parameters to your method. (And you can even pass it a file) as parameters, just give the parameter name to your file. (but you have to report it in filePocket)

🚧 How Quest works

Quest is based on PHP attributes. It goes through all your references and creates a registry of the methods you have marked. A method is marked by a reference key that serves as a reference point for quest to call your method.

To create a reference:

🧩 Usage

Let's start by defining our route with Quest:

Hacp0012\Quest is the main namespace. Contains the Quest() class and the QuestRouter() class and the QuestSpawMethod enum. Then there is the namespace Hacp0012\Quest\Attributes, which contains the Quest attributes. Such as QuestSpaw() and QuestSpawClass().

You can add middlewares and such because Quest's static spawn function returns an object of type Illuminate\Routing\Route so it supports all other methods of the Route facade.

Note that the Forest class has been added to the list of routes in the spaw(..., routes: [Forest::class]) method.

Let's now define our Forest class which will contain our methods referenced by spaw. punched.

And that's it, now you can start calling your methods punched (referenced) by their reference key ref: 'NAhLlRZW3g3Fbh30dZ'.

Note that you can use any phrase as a reference. Although quest allows you to generate unique keys. You can use something like: forest.app.tree.NAhLlRZW3g3Fbh30dZ. Or see the CLI command reference for more details

As in this example above:

_quest_ref is the parameter key of the route generated by Quest. The kind of parameters that we pass in the url: https://moonsite.com/my/quest/{quest_ref}_

🔖 There is another way to call Quest. That is to pass QuestRouter and create a router object, like this:

Or

⚠️ Even though this is not the cleanest method, I advise you not to use it because it can give you weird return types that even Laravel's Service container won't be able to interpret.

Service container

Laravel provides an automatic dependency injection system that it calls Service Container. It is able to construct an object that you have declared as a parameter.

Take this as a reminder:

Well Quest can't spoil this happiness. Quest also resolves your objects declared in the parameters. In any case feel free to do what you want.

🪄 Try and you will know. 🧙‍♂️

👽 CLI Commandes

php artisan quest:ref [--list [--no-table] [--index=n]] [--generate=n] [--track=''] see in doc.

php artisan quest:generate-ref [36] [--uuid]

Generate a reference key. But this does not prevent you from taking any text for reference. This is just a help, to allow you to do something unique.

If you add the --uuid option, it will generate a UUID key and ignore the length you specified. UUIDs are 36 characters long (they are unique anyway)

By default the command generates 36 random characters.

php artisan quest:generate-ref

php artisan quest:track-ref [ref-id]

Track the reference of a pointed method (spawed)

Among the good things, there is the ref tracker. This tracker is great, it allows you to find yourself more easily and find the implementation of your method.

php artisan quest:track-ref RrOWXRfKOjauvSpc7y

Because let's be serious, the reference key system can be a little more constipating when you don't have a very solid architecture or when you are a beginner. This is why I advise you not to rely only on the keys generated by the quest:generate-ref command, get into the habit of adding a few words called human readable. Ex. 'my.forest.trees.meXRQbm0WQP6ZpAN5U'

To check the quest version:

php artisan about

This is an internal command of Laravel

🔆 Api reference

• Quest Attributs
• Quest class
• Quest Router
• CLI Commands

Best practices

The type of return in comment

Let's take this example:

Please specify the return type and details about it, because the tracker returns the PHP-Doc comments of the method. This will help you to have a direct idea of ​​what is returned by the call.

Things to add

• Temporary routes.

FAQ

How can I do my request validations ?

First of all the method parameters are also another type of validation but low level. You can retrieve all your request parameters via the Request object like this:

By default, quest supports some basic (native) types ['bool', 'int', 'float', 'string', 'null', 'array', 'mixed', UploadedFile::class] and the one you linked in Service Container via Provider. Other types are not supported. The reason is that over HTTP(S) we don't often transfer objects. It's often text and often formatted in JSON. So the basic (native) types are often the same types that the JSON annotation supports.