Usage

The Package GUI

It is easy when you don't have to deal with the command line, so we've created an elegant interface to make your experience smoother . you can use it after installing the package by visiting the url :

http://localhost/your-project-folder-name/public/cubeta-starter

This interface will work only on the local environment .

Available Commands

The package provide commands similar to the laravel base commands with the same functionality with the benefit of getting a full generated CRUD support code from them .

the commands :

1. php artisan cubeta:install api
2. php artisan cubeta:install web
3. php artisan cubeta:install auth
4. php artisan cubeta:install react-ts
5. php artisan cubeta:install react-ts-packages
6. php artisan cubeta:install web-packages
7. php artisan cubeta:install permissions
8. php artisan create:actor
9. php artisan create:model
10. php artisan create:migration
11. php artisan create:factory
12. php artisan create:seeder
13. php artisan create:request
14. php artisan create:repository
15. php artisan create:service
16. php artisan create:resource
17. php artisan create:controller
18. php artisan create:web-controller
19. php artisan create:test

Now those commands depends on 7 parameters (of course not the 7 parameters required for each command) but I can tell you the most important one is the model name so for each command you have to provide the model name that the generated file will target .

The seven parameters are :

parameter	type
Model name	string
Table columns and their types	array[colName:string => colType:string]
The model relations	array[relationName:string => relationType:string]
The nullable columns for this model	array[colNames]
the unique columns for this model	array[colNames]
the actor (this for the generated controller)	string
container (which mean api or web)	string in [api , web , both]

All the commands accept those parameters but not all of them is required so instead of providing them manually just type the command and the command will ask you about just the required parameters.

by default the package will handle the naming of your created files, so it will fit in the laravel naming convention principle (like if you put products as a model name the package will automatically set it to Product ), but it is always better to provide the right names to the commands instead on depending on them in case of facing an unexpected behaviour .

NOTE

The actor parameter will define the actor on the created endpoints, and it is important for route placing and naming , you'll be asked about it if you used our roles permission tool via the command php artisan cubeta:install permissions.

Install Permissions Command

In previous versions we used spatie/laravel-permission which is a great package but to lightweight your project and make it optional to you use it or not or to edit the way it works we have powered you with the command php artisan cubeta:install permissions which will generate the following files for you :

1. RoleDoesNotExistException ( exception class )
2. ActionsMustBeAuthorized ( interface for models )
3. ModelHasPermission ( model )
4. ModelHasRole ( model )
5. Role ( model )
6. HasPermissions ( trait )
7. HasRoles ( trait )
8. migration files for the generated models

now you can handle your actor roles and permissions easily and with an opinionated way

check the usage manual here .

Install Auth Command

To prepare your project to handle authentication and authorization we've provided a seamless way for this by executing the command : php artisan cubeta:install auth this command will initialize your project with the following :

1. BaseAuthController ( Controller )
2. AuthLoginRequest ( Form Request )
3. AuthRegisterRequest ( Form Request )
4. CheckPasswordResetCodeRequest ( Form Request )
5. RequestResetPasswordRequest ( Form Request )
6. ResetPasswordRequest ( Form Request )
7. UpdateUserRequest ( Form Request )
8. UserResource ( Json Resource )
9. User.php ( Model ) ( this will override the existing User.php model file so be careful )
10. UserRepository ( Repository Class )
11. UserService ( Service Class )
12. 2014_10_12_000000_create_users_table.php ( migration ) ( this will override the existing users table migration file so be careful )
13. ResetPasswordCodeEmail ( Notification )
14. set of routes for the dashboard authentication ( for web )
15. reset-password-email.blade.php ( view )
16. set of views for the authentication process ( for web )
17. a set of pages to handle your authentication flow based on your frontend stack

Now as you see you are now ready to create your authentication endpoints powered up by those files and classes

Looking at the generated files you should focus on two files the first is : UserService.php and BaseAuthController.php as you will notice that the UserService class handle the authentication logic for both use cases ( api and web ) and the class BaseAuthController use the UserService in a way that allows you to extend it for every actor you want.

Create Actor Command

This command will add the desired actor roles to your project like when you have (admin , customer , ....) roles in your project

NOTE

using this command require you to install the Permissions Feature by executing the command php artisan cubeta:install permissions

WARNING

make sure that your user model uses the HasRoles trait

how to use it :

1- run this command : php artisan create:actor so an output will appear :

What Is The Actor Name ? i.e:admin , customer , ... :    
> student

just put the name for this actor and press enter so the following output will appear :

Does This Actor Has A Specific Permissions You Want o Specify ? (student) (yes/no) [no]:

Now the command asking if you would like to specify permissions for this role so just type in like this :

 Does This Actor Has A Specific Permissions You Want o Specify ? (student) (yes/no) [no]:                                                   
 > yes

Now just enter the permissions like this :

What Are (student) Permissions ?                                                                                                           
Write As Many Permissions You Want Just Keep Between Every Permissions And The Another A Comma i.e : can-read,can-index,can-edit:           
 > index,create,update,delete

Now the command will ask you about the container (as you'll see the package will distribute the generated endpoints to a route files named after your project actors so when adding new actor new route file will be added for him, so you have to specify the container for that file)

 What Is The Container Type For This Operation :  [api]:                                                                                    
  [0] api                                                                                                                                   
  [1] web                                                                                                                                   
  [2] both                                                                                                                                  
 > 0

Now this question will appear :

Do You Want To Create Authentication Api Controller For This Actor ? (yes/no) [yes]:                                                       
 > yes

by confirming you are generating Authentication controller for your actor .

The last question is :

Do You Want To Create Authentication Api Controller For This Actor ? (yes/no) [yes]:                                                       
 > yes

NOTE

You have to run php artisan cubeta:install auth if you'd like to create an authentication controller for your actor

Now you will notice that the there is multiple files generated and some changes in your project files:

1. RolesPermissionsEnum.php (basically in app/Enums Directory )
2. routes files named by your actor
3. StudentAuthController.php
4. RoleSeeder
5. student.php route file
6. the RouteServiceProvider.php in app/Providers directory has been changed to add the student.php route file to your app routes
7. the student.php and public.php route files has the auth routes for the generated controller

WARNING

when overriding any file with the same name and directory of the generated file will be lost so be careful

NOTE

this command works with the generated files of these commands : cubeta:install permissions , cubeta:install auth so make sure that you follow their steps before start adding actors

If you do a little check on app/Enums/RolesPermissions.php you'll find that your actor has been added to it .

now if you opened the generated StudentAuthController you'll see the following

namespace App\Http\Controllers\API\v1;

use App\Enums\RolesPermissionEnum;
use App\Services\User\UserService;

class StudentAuthController extends BaseAuthController
{
    public function __construct()
    {
        parent::__construct();
        $this->roleHook(RolesPermissionEnum::STUDENT['role']);
    }
}

NOTE

all the namespaces and the generated directories are based on the config you defined in the config/cubeta-starter.php file

as this class extend the BaseAuthController controller class then it will has all public and protected methods defined in it so if you opened the routes/v1/api/public.php route file you'll see that the generated routes are using the same methods exist in the BaseAuthController class

now let us assume that you want to add a specific logic when you register a new student in the BaseAuthController class you'll see that this is the register method :

public function register(AuthRegisterRequest $request)
    {
        [$user , $token, $refresh_token] = $this->userService->register($request->validated(), $this->role);

        return rest()->ok()->data([
            'user' => new UserResource($user) ,
            'token' => $token ,
            'refresh_token' => $refresh_token
        ])->message(__('site.registered_successfully'))
        ->send();
    }

so in your generated controller i.e : StudentAuthController all what you have to do is to add the following method to it :

// or whatever namespace you defined in the package config file
use App\Http\Requests\AuthRequests\AuthRegisterRequest;

public function register(AuthRegisterRequest $request)
{
    // your specific logic
}

or if you want to extend its logic and save the BaseAuthController register method logic

public function register(AuthRegisterRequest $request)
{
    // add your specific logic here ...
  
    return parent::register($request);
}

NOTE

the base purpose of this package isn't to strict you with specific ways to handle your project but is to give you classes and traits and tools in your project code so that you can edit them as you want so dig in and start scanning the code

Generating Files

As mentioned before you can run every command in the list of the available commands separately and for a full generated CRUD run create:model command without any options like this :

1 - run this command : php artisan create:model <YourMoodel> then an output will show :

2 - write your model properties that will correspond to its table columns like this :

Enter your params like "name,started_at,...":
> name,email,password

then an output for each property of your model will appear like this :

What is the data type of the (( name field )) ? default is  [string]:
  [0 ] integer
  [1 ] bigInteger
  [2 ] unsignedBigInteger
  [3 ] double
  [4 ] float
  [5 ] string
  [6 ] text
  [7 ] json
  [8 ] boolean
  [9 ] date
  [10] time
  [11] dateTime
  [12] timestamp
  [13] file
  [14] key
  [15] translatable

those are the column type you just enter the number of the type

NOTE

the key type is a foreignId so if your column name is something like this : user_id you need to define it as a key type

Translatable Column Type

Of course there isn't a column type called translatable in Laravel . to make it easier for you to use the prepared things for the translation we called this column translatable in fact the generated column type is json but in this way we've marked this column as translatable so the generated code will make sure to use the ValidTranslatableJson validation rule on the validation and cast this column to Translatable::class .

the Translatable::class is a custom cast class you can check on it in app/Casts directory , and its job is to cast the translated value (basically JSON string) to \App\Serializers\Translatable object which class that will make your localized data handling easier check on it here.

The ValidTranslatableJson validation rule will make sure that the received json is simple and hasn't any nesting objects e.g :

{
    "en": "name",
    "fr": "nom"
}

and not something like this for example

[
    {
        "en": "name",
        "fr": [
            {
                "ar": "اسم"
            }
        ]
    }
]

and in addition to that it's make sure that the entered translation is corresponding to one of the locales defined in the config/cubeta-starter.php config file if it is not it will return a validation error.

3 - then the output will be :

Is This Column Nullable ? (yes/no) [no]:
 > no

just chose whether the column is nullable or not

4 - then this question will appear :

Is This Column Unique ? (yes/no) [no]:
 > no

just chose whether the column is unique or not

Does (<YourModelName>) model related with another model by has many relation ? (yes/no) [no]:
 > yes

if you hit yes it will ask you about the name of the related model so just type it then it will re-ask you if you have another has many related model just do the same

4 - this output will come next :

Does (<YourModelName>) model related with another model by many to many relation ? (yes/no) [no]:
 > yes

so just like before type the model name if you're willing to hit yes

now we're done for this part

so you will find a :

1. your model class
2. migration for your model
3. factory for your model
4. seeder for your model
5. request for your model if you've chosen api instead of web
6. controller filled with CRUD methods
7. named resource rout for your controller will be appended in the appropriate route file
8. repository class for your model
9. service class and its interface for your model
10. test class for your model with a test for CRUD operations
11. postman collection

NOTE

After the first generation a cubeta-starter.config.json file will be created in the base directory of your project. It tracks your generated tables, chosen frontend stack, and which parts of the package you've installed. The package reads it to power the GUI and to make smarter decisions on subsequent generations, so keep it under version control and avoid editing it by hand.

Create Model Command Options

if you'd like you can generate the model with just a specific file you can just add the desired file as an option like if you execute this command :

php artisan create:model Product --controller --resource

this command will generate the product model with a corresponding resource and controller .

NOTE

when not providing an option to the command it will generate the model and all its related files as we said before

the available options for these commands are :

1. --migration
2. --request
3. --resource
4. --factory
5. --seeder
6. --repository
7. --service
8. --controller
9. --web_controller
10. --test

NOTE

you cannot do the same thing using the gui . you have to generate every file alone but instead you have a full generation operation page to generate the whole files with the model