{"id":17505177,"url":"https://github.com/mustafakhaleddev/laravel-state-management","last_synced_at":"2025-07-09T17:08:51.062Z","repository":{"id":258003664,"uuid":"873977788","full_name":"mustafakhaleddev/laravel-state-management","owner":"mustafakhaleddev","description":"a state management package for Laravel, enabling shared and persistent application state across services, requests, and files without the need for reinitialization. It supports casting, default state handling, and custom methods for managing complex state in your Laravel applications","archived":false,"fork":false,"pushed_at":"2024-10-18T21:32:38.000Z","size":17,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-11T03:06:18.693Z","etag":null,"topics":["laravel","laravel-framework","laravel-package","state-machine","state-management","states"],"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/mustafakhaleddev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","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":"2024-10-17T03:36:14.000Z","updated_at":"2024-11-03T13:17:42.000Z","dependencies_parsed_at":"2024-12-08T12:25:56.267Z","dependency_job_id":"1e17a3fa-65bf-4569-b07c-0d017cbdd9c0","html_url":"https://github.com/mustafakhaleddev/laravel-state-management","commit_stats":{"total_commits":3,"total_committers":1,"mean_commits":3.0,"dds":0.0,"last_synced_commit":"fc44bce03b1a0619a203564de67b13d9eb3af8cb"},"previous_names":["mustafakhaleddev/laravel-state-management"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/mustafakhaleddev/laravel-state-management","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mustafakhaleddev%2Flaravel-state-management","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mustafakhaleddev%2Flaravel-state-management/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mustafakhaleddev%2Flaravel-state-management/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mustafakhaleddev%2Flaravel-state-management/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mustafakhaleddev","download_url":"https://codeload.github.com/mustafakhaleddev/laravel-state-management/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mustafakhaleddev%2Flaravel-state-management/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264502167,"owners_count":23618557,"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":["laravel","laravel-framework","laravel-package","state-machine","state-management","states"],"created_at":"2024-10-20T02:15:55.408Z","updated_at":"2025-07-09T17:08:50.961Z","avatar_url":"https://github.com/mustafakhaleddev.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Laravel State Management\n\nA state management solution for Laravel applications inspired by Redux, designed to manage complex application state across services, caching layers, and requests, with support for casting, default state handling, and custom methods.\n\n## Features\n- **Shared State Across Application**:Stores are shared globally across the application, making them easily accessible without reinitialization in multiple files.\n- **State Persistence and Rehydration**: Manage application state easily, persisting and rehydrating data as needed.\n- **Casting Attributes**: Automatically cast attributes to types like collections or custom classes using Laravel's castable functionality.\n- **Default State Handling**: Define fallback states to be used when rehydration fails.\n- **Custom Store Logic**: Add custom methods to interact with specific store states and manage application logic.\n\n## Installation\n\nInstall the package using Composer:\n\n```bash\ncomposer require mkd/laravel-state-management\n```\n\n## Basic Usage\n\n### Step 1: Create a Store\n\nYou can create a store class using the `store:make` Artisan command:\n\n```bash\nphp artisan store:make UserStore\n```\n\nThis command will generate a new store class in your `app/Stores` directory.\n\n### Step 2: Define Your Store\n\nIn the generated store, define your attributes and casts. The store will manage the state related to these attributes:\n\n```php\nclass UserStore extends StoreContract\n{\n    protected $attributes = [\n        'user',\n        'email',\n        'status'\n    ];\n\n    protected $casts = [\n        'email' =\u003e StringCast::class,  // Custom cast\n    ];\n\n    protected $enums = [\n        'status' =\u003e CustomStatusEnum::class // Use enums for statuses\n    ];\n\n    public function default(): array\n    {\n        return ['user' =\u003e User::find($this-\u003ekey)]; // Fallback if rehydration fails\n    }\n\n    public function updateUserName($name)\n    {\n        $user = $this-\u003egetUser();\n        $user-\u003ename = $name;\n        $user-\u003esave();\n    }\n}\n```\n\n### Step 3: Using a Store\n\nTo interact with a store and manage the state, you can retrieve the store instance and access its methods:\n\n```php\nuse App\\Stores\\UserStore;\n\npublic function handleState(StateManagement $stateManagement)\n{\n    // Retrieve the store and set state values\n    $userStore = $stateManagement-\u003estore(UserStore::class);\n    $userStore-\u003esetUser(User::first());\n\n    // Call custom methods to manage store data\n    $userStore-\u003eupdateUserName('New Name');\n}\n```\n\n### Step 4: Handling Persistent State\n\nYou can persist and rehydrate states based on a unique key, enabling state restoration between requests:\n\n```php\n$userStore = StateManagement::use(UserStore::class);\n$userStore-\u003esetKey(1);\n$userStore-\u003erehydrate();\n$status = $userStore-\u003egetStatus(); // Retrieve status from the store\n```\n\n### Step 5: Defining Custom Casts\n\nIf you need custom casting for certain attributes, use the `store-cast:make` command:\n\n```bash\nphp artisan store-cast:make EmailCast\n```\n\nThen, define the casting logic in the generated cast class:\n\n```php\nclass EmailCast implements StateCastAttribute\n{\n    public function get($model, string $key, $value, array $attributes)\n    {\n        return strtolower($value);\n    }\n\n    public function set($model, string $key, $value, array $attributes)\n    {\n        return strtoupper($value);\n    }\n}\n```\n\n### Store Rehydration Example\n\n```php\n$settingsStore = StateManagement::use(SettingsStore::class);\n$settingsStore-\u003esetKey(auth()-\u003euser()-\u003eid);\n$settingsStore-\u003erehydrate();\n$countries = $settingsStore-\u003egetCountries();\n```\n\n## Commands\n\n- `store:make \u003cStoreName\u003e`: Generates a new store class.\n- `store-cast:make \u003cCastName\u003e`: Generates a new custom cast class.\n\n## Example Stores\n\n### `SettingsStore`\n\nThis store manages application settings and allows for the dynamic update of user preferences.\n\n```php\nclass SettingsStore extends StoreContract\n{\n    protected $attributes = ['countries', 'cities', 'user'];\n    \n    protected $casts = ['countries' =\u003e CollectionCast::class, 'cities' =\u003e CollectionCast::class];\n    \n    public function default(): array\n    {\n        return ['countries' =\u003e ['id' =\u003e 1, 'name' =\u003e 'USA'], 'cities' =\u003e ['id' =\u003e 2, 'name' =\u003e 'New York']];\n    }\n\n    public function updateUserSettings($key, $value)\n    {\n        $this-\u003egetUser()-\u003eupdateSettings($key, $value);\n    }\n}\n```\n\n### `UserNotification`\n\nThis store handles sending notifications, such as emails, to users.\n\n```php\nclass UserNotification extends StoreContract\n{\n    protected $attributes = ['user', 'email'];\n    \n    protected $casts = ['email' =\u003e EmailCast::class];\n    \n    public function sendInvoiceEmail(Invoice $invoice)\n    {\n        $this-\u003egetUser()-\u003enotify(new InvoiceEmail($invoice));\n    }\n}\n```\n\n ### `Persist`\nBy Default Persist is saving the state object in cache so it can be easy rehydrated later with the key\n```php\nuse App\\Stores\\UserStore;\n\npublic function handleState(StateManagement $stateManagement)\n{\n    $user = User::first();\n    // Retrieve the store and set state values\n    $userStore = $stateManagement-\u003estore(UserStore::class);\n    $userStore-\u003esetUser($user);\n    $userStore-\u003esetKey($user-\u003eid);\n\n    // Call custom methods to manage store data\n    $userStore-\u003eupdateUserName('New Name');\n    $userStore-\u003epersist();\n}\n```\nYou can override `persist` logic by implementing your own logic in store class\n```php\n    public function persistUsing()\n    {\n        //Your own persist logic\n        \n        //Init custom persist flag\n        $this-\u003einitCustomPersist()\n    }\n```\n\n### `rehydrate`\nBy Default rehydrate is setting the state from cache based on store key\n```php\nuse App\\Stores\\UserStore;\n\npublic function handleState(StateManagement $stateManagement)\n{\n    $user = User::first();\n    // Retrieve the store and set state values\n    $userStore = $stateManagement-\u003estore(UserStore::class);\n    $userStore-\u003esetKey($user-\u003eid);\n    $userStore-\u003erehydrate();\n    $userStore-\u003egetUser()-\u003ename // 'New Name'\n}\n```\nYou can override `rehydrate` logic by implementing your own logic in store class\n```php\n    public function rehydrateUsing()\n    {\n        // your own rehydrating logic\n        \n        //Init custom rehydrate flag\n        $this-\u003einitCustomRehydrate();\n    }\n```\n## License\n\nThis package is open-sourced software licensed under the [MIT license](LICENSE.md).\n\n---\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmustafakhaleddev%2Flaravel-state-management","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmustafakhaleddev%2Flaravel-state-management","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmustafakhaleddev%2Flaravel-state-management/lists"}