Download the PHP package projectsaturnstudios/pss-event-sourcing without Composer

On this page you can find all versions of the php package projectsaturnstudios/pss-event-sourcing. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package pss-event-sourcing

Project Saturn Studios - Laravel ES Utilities 🚀

Latest Version on Packagist Total Downloads

Supercharge your Spatie Event Sourcing with the elegance of Spatie's Laravel-Data objects and the power of Loris Leiva's Laravel Actions. This package is all about making event sourcing in Laravel a smoother, more typed, and downright enjoyable ride.

📜 Table of Contents

🤔 Why This Package?

Event sourcing is a powerful pattern, and Spatie's laravel-event-sourcing package provides a rock-solid foundation for it in Laravel. So, why add another layer with laravel-es-utilities? Glad you asked, partner. This package is all about taking that solid foundation and making your developer experience (DX) even smoother, more robust, and, dare we say, more enjoyable.

Here's the lowdown on what this package brings to your shindig:

In short, if you love spatie/laravel-event-sourcing but wished for tighter integration with typed data objects and a more structured approach to commands, laravel-es-utilities is here to be your new best friend.

✨ Features List

This package is packed with goodies to make your event sourcing journey in Laravel smoother. Here are the highlights:

📦 Installation

You can install the package via Composer:

The package leverages Laravel's package auto-discovery, so you typically won't need to manually register the service provider (ProjectSaturnStudios\EventSourcing\Providers\PSSEventSourcingServiceProvider).

This service provider will automatically merge the necessary configuration to use the custom ProjectSaturnStudios\EventSourcing\Serializers\EventSerializer for handling DataEvent objects. This ensures your typed event data is correctly serialized and deserialized using spatie/laravel-data capabilities.

Optional: Publishing Configuration

If you wish to customize the event sourcing configuration further (beyond what this package provides by default), you can publish Spatie's main event sourcing configuration file. Note that this package already sets the recommended event_serializer. If you publish and modify Spatie's config, ensure you retain or re-configure the event_serializer to point to ProjectSaturnStudios\EventSourcing\Serializers\EventSerializer::class if you want to continue using this package's DataEvent serialization.

To publish Spatie's configuration (if you haven't already for spatie/laravel-event-sourcing):

This will create a config/event-sourcing.php file in your application's config directory. Again, for this package (projectsaturnstudios/laravel-es-utilities) to work as intended with DataEvent objects, the event_serializer in that published config should be:

Our package attempts to set this for you by default through its own service provider's config merging. Publishing is only needed if you require deeper customization of other Spatie event sourcing settings.

⚙️ Configuration

This package is designed to work with minimal configuration out-of-the-box.

Event Serializer

The most crucial piece of configuration is the event_serializer. Our ProjectSaturnStudios\EventSourcing\Providers\PSSEventSourcingServiceProvider automatically merges its configuration to set the event_serializer in your config/event-sourcing.php to use ProjectSaturnStudios\EventSourcing\Serializers\EventSerializer::class.

This ensures that your DataEvent objects are correctly handled. No manual configuration is typically needed for this.

If you publish the spatie/laravel-event-sourcing configuration file (php artisan vendor:publish --provider="Spatie\EventSourcing\EventSourcingServiceProvider" --tag="event-sourcing-config"), you'll see this setting:

If you override this, ensure you understand the implications for DataEvent serialization.

Queue Prefixing (app_queue() helper)

The app_queue(string $key): string helper function allows you to prefix your queue names. It looks for an environment variable:

This is useful for namespacing queues in different environments or applications sharing a Redis instance.

RetryPersistMiddleware

The ProjectSaturnStudios\EventSourcing\Middleware\RetryPersistMiddleware used by the event_command() helper defaults to 3 retry attempts. If you were to use this middleware manually with Spatie's Command Bus, you could configure the number of retries via its constructor:

However, when using the event_command() helper, it defaults to 3 retries, which is generally a sensible default.

Other Spatie Event Sourcing Configuration

For all other event sourcing configurations (e.g., projectors, reactors, stored event repository, snapshot repository), please refer to the official spatie/laravel-event-sourcing package documentation and its config/event-sourcing.php file. This package primarily focuses on enhancing the event and command handling aspects.

🚀 How to Rock It (Usage Guide)

Alright, let's get down to brass tacks. Here's how you can use this package to make your event sourcing life a little more zen.

Defining Your DataEvent

First up, you'll want to define your domain events as DataEvent objects. These are essentially Spatie\LaravelData\Data objects that also extend ProjectSaturnStudios\EventSourcing\Events\DataEvent. This base class provides the necessary integration with Spatie's event sourcing system and Laravel Data's features.

Example: Let's say we're building a simple "Todo" application and want an event for when a task is created.

Key Benefits Here:

Crafting Your EventCommand

Next, you'll create EventCommand classes. These are responsible for taking input, performing any necessary validation or business logic, and then creating the appropriate DataEvent. We recommend using lorisleiva/laravel-actions for these commands, and they can extend the base ProjectSaturnStudios\EventSourcing\EventCommands\EventCommand (though this base class is simple and mainly for type-hinting or namespacing).

Example: A command to create our TodoTask.

Key Points for EventCommands:

Dispatching with event_command()

Once you have your EventCommand defined, you'll want to dispatch it. This package provides a convenient global helper function event_command() for this purpose.

This helper function uses the ProjectSaturnStudios\EventSourcing\Actions\DispatchEventCommand action internally, which in turn uses Spatie's Command Bus. By default, if you don't specify any middleware, event_command() applies the ProjectSaturnStudios\EventSourcing\Middleware\RetryPersistMiddleware.

Example: Dispatching our CreateTodoTask command.

If you need to use custom middleware, or want to change the retry behavior:

Working with Aggregates

Your EventCommand handlers will typically interact with Aggregate Roots (from spatie/laravel-event-sourcing). The aggregate is responsible for upholding business rules and recording events that result from command processing.

Example Aggregate (TodoTaskAggregate):

Let's sketch out what our TodoTaskAggregate might look like. It would extend Spatie\EventSourcing\AggregateRoots\AggregateRoot (or our ProjectSaturnStudios\EventSourcing\Aggregates\AlternativeAggregateRoot if you need its specific features).

Key Interactions:

Revised CreateTodoTask Command (showing aggregate interaction more clearly):

Implicit Benefits: RetryPersistMiddleware & EventSerializer

It's worth reiterating two key components that work quietly in the background to make your life easier when using the patterns described above:

These features are designed to provide a more robust and developer-friendly experience with minimal effort on your part.

✅ Testing Your Masterpiece

Testing is crucial for event-sourced applications. Here's how you can approach testing different parts of your system when using laravel-es-utilities.

Testing EventCommand Actions

Since your EventCommand classes are built using lorisleiva/laravel-actions, you can test them like any other Laravel Action. You can unit test them by directly instantiating and calling the handle method, or test them as part of a feature test.

Key things to assert:

Spatie's laravel-event-sourcing package provides excellent testing tools for aggregates:

Testing Aggregates

Spatie's laravel-event-sourcing package provides powerful testing methods directly on your aggregate roots.

Key aggregate testing methods:

Testing Projectors and Reactors

Refer to the spatie/laravel-event-sourcing documentation for detailed guidance on testing projectors and reactors. They also have dedicated testing tools.

This package focuses on the command and event creation side, so ensure your DataEvent objects and EventCommand actions integrate well with your aggregates, and then leverage Spatie's tools for the rest.

🔮 Advanced Scenarios / Cookbook

Here are a couple of scenarios or tools within the package that go beyond the basic setup.

Using AlternativeAggregateRoot

If you have specific needs for how your aggregate roots interact with event or snapshot repositories (for example, using different database connections or custom repository implementations for certain aggregates), this package provides an AlternativeAggregateRoot.

You can extend ProjectSaturnStudios\EventSourcing\Aggregates\AlternativeAggregateRoot instead of the default Spatie\EventSourcing\AggregateRoots\AggregateRoot. Then, within your aggregate, you can specify the classes for your custom repositories:

Your custom repository classes (MyCustomEventRepository, MyCustomSnapshotRepository) must implement the respective interfaces expected by Spatie's event sourcing package (e.g., Spatie\EventSourcing\StoredEvents\Repositories\StoredEventRepository and Spatie\EventSourcing\Snapshots\SnapshotRepository).

This gives you fine-grained control over persistence mechanisms for specific aggregates without altering the global defaults.

Using the app_queue() Helper

The app_queue(string $key): string helper function is a simple utility for prefixing your queue names based on an environment variable. This is particularly useful if you're running multiple applications or environments that might share a queueing backend (like Redis) and you want to avoid queue name collisions.

How it works:

  1. Define an environment variable, for example, in your .env file:

  2. When you use the helper:

  3. If QS_PREFIX is not set or is empty, app_queue('events') will simply return 'events'.

You can use this helper anywhere you define queue names, such as in your event listeners, jobs, or in the Spatie event sourcing configuration (config/event-sourcing.php for the main event queue).

Example in config/event-sourcing.php:

This helps keep your queue management clean and organized across different environments.

🙌 Contributing

We welcome contributions from the community! If you're interested in contributing to this package, please follow these steps:

  1. Fork the repository on GitHub.
  2. Create a new branch for your feature or bug fix.
  3. Make your changes in the new branch.
  4. Write tests for your changes.
  5. Submit a pull request.

🙌 Support & Contact

If you encounter any issues or have questions about this package, please feel free to open an issue on GitHub or contact us directly.

📄 License

This package is open-source and released under the MIT License. See the LICENSE file for more information.

📋 Credits & Thanks

This package was created by Project Saturn Studios. We're grateful for the contributions of the community and the support of our users.

📜 README Change Log

See the CHANGELOG file for a detailed history of changes to this README.


All versions of pss-event-sourcing with dependencies

PHP Build Version
Package Version
Requires php Version ^8.2
ext-pdo Version *
spatie/laravel-data Version ^4.11
lorisleiva/laravel-actions Version ^2.6
spatie/laravel-event-sourcing Version ^7.3
ramsey/uuid Version ^4.7
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package projectsaturnstudios/pss-event-sourcing contains the following files

Loading the files please wait ....