diff --git a/README.md b/README.md index 029fff4..a7a816f 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [![Latest Version on Packagist](https://img.shields.io/packagist/v/cleaniquecoders/laravel-action.svg?style=flat-square)](https://packagist.org/packages/cleaniquecoders/laravel-action) [![PHPStan](https://github.com/cleaniquecoders/laravel-action/actions/workflows/phpstan.yml/badge.svg)](https://github.com/cleaniquecoders/laravel-action/actions/workflows/phpstan.yml) [![run-tests](https://github.com/cleaniquecoders/laravel-action/actions/workflows/run-tests.yml/badge.svg)](https://github.com/cleaniquecoders/laravel-action/actions/workflows/run-tests.yml) [![Fix PHP code style issues](https://github.com/cleaniquecoders/laravel-action/actions/workflows/fix-styling.yml/badge.svg)](https://github.com/cleaniquecoders/laravel-action/actions/workflows/fix-styling.yml) [![Total Downloads](https://img.shields.io/packagist/dt/cleaniquecoders/laravel-action.svg?style=flat-square)](https://packagist.org/packages/cleaniquecoders/laravel-action) -Simple Actionable for Laravel. +This package, **Simple Actionable for Laravel**, provides a structured way to manage action classes in your Laravel applications, making it easier to encapsulate business logic, transformations, and validations within reusable classes. The package utilizes [lorisleiva/laravel-actions](https://github.com/lorisleiva/laravel-actions) to offer extended functionality, enabling actions to be executed in multiple contexts (e.g., jobs, controllers, event listeners) and simplifying your codebase. ## Installation @@ -12,9 +12,13 @@ You can install the package via composer: composer require cleaniquecoders/laravel-action ``` -## Todo +## Features -- [ ] Be able to publish stubs and using custom stubs if exists. +This package builds on top of `lorisleiva/laravel-actions`, allowing you to: +- Create versatile action classes that can be executed as invokable objects, controllers, or dispatched as jobs. +- Use property setters to configure actions dynamically. +- Apply transformations like hashing or encryption to specific fields. +- Manage `updateOrCreate` behavior with constraints on unique fields. ## Usage @@ -53,7 +57,7 @@ class CreateOrUpdateUser extends ResourceAction #### 1. Flexible Property Setter -You can now set various properties, like `hashFields`, `encryptFields`, and `constrainedBy`, dynamically using the `setProperty` method: +You can set properties, such as `hashFields`, `encryptFields`, and `constrainedBy`, dynamically using the `setProperty` method: ```php $action = new CreateOrUpdateUser(['name' => 'John Doe', 'email' => 'johndoe@example.com', 'password' => 'secretpassword']); @@ -62,7 +66,7 @@ $action->setProperty('encryptFields', ['ssn']); // Encrypt SSN $action->setProperty('constrainedBy', ['email' => 'johndoe@example.com']); // Use email as a unique constraint ``` -This flexible property setting reduces boilerplate and simplifies configuration of actions. +This flexible property setting reduces boilerplate and simplifies action configuration. #### 2. Field Transformation with Hashing and Encryption @@ -79,7 +83,7 @@ $inputs = [ $action = new CreateOrUpdateUser($inputs); $action->setProperty('hashFields', ['password']); $action->setProperty('encryptFields', ['ssn']); -$record = $action->execute(); +$record = $action->handle(); ``` After execution: @@ -88,7 +92,7 @@ After execution: #### 3. Constraint-Based `updateOrCreate` -You can specify constraints to perform `updateOrCreate` actions based on unique fields or identifiers. Here’s an example of updating an existing user by `id`: +Specify constraints to perform `updateOrCreate` actions based on unique fields or identifiers. Here’s an example of updating an existing user by `id`: ```php // Assume there's an existing user with this email @@ -108,13 +112,33 @@ $inputs = [ $action = new CreateOrUpdateUser($inputs); $action->setProperty('constrainedBy', ['id' => $existingUser->id]); // Update by user ID -$record = $action->execute(); +$record = $action->handle(); // The existing user record with the specified ID will be updated. ``` This allows precise control over `updateOrCreate` behavior based on custom constraints. +## Using `lorisleiva/laravel-actions` for Multi-Context Execution + +With `lorisleiva/laravel-actions`, actions created with this package can be used in multiple contexts. You can run the action as: +- **An Invokable Object**: + ```php + $user = (new CreateOrUpdateUser(['name' => 'Jane', 'email' => 'jane@example.com']))->handle(); + ``` +- **A Controller**: + ```php + Route::post('users', CreateOrUpdateUser::class); + ``` +- **A Job**: + ```php + CreateOrUpdateUser::dispatch(['name' => 'Jane', 'email' => 'jane@example.com']); + ``` +- **An Event Listener**: + ```php + Event::listen(UserRegistered::class, CreateOrUpdateUser::class); + ``` + ## Testing Run the tests with: