Download the PHP package italystrap/event without Composer

ItalyStrap PSR-14 Event API integrations with WordPress and WordPress Plugin API implementation

PSR-14 Event Dispatcher implementation for WordPress and wrappers around the WordPress Plugin API (Events aka Hooks)

[!IMPORTANT] It is still a WIP

Please, even if it works very well, also the PSR-14 implementation works very well, keep in mind that this is still a WIP until this package reach the version 1.x.x, for now it is a 0.x.x version (if you don't know what this means, please read the SemVer specification).

Personally I'm very proud of this package (like I'm proud for all the others 😊), at the end it was not very complicated to implement the PSR-14 standard, but I needed to hack a little bit the WordPress Plugin API to make it work as expected.

BTW, I'm using this package in production for my own projects and right now I have no issue, if you find some please, please, let me know opening an issue (or a PR if you want to fix it), here the link to the issue tracker.

The naming convention I used is: when you encounter the word Global* means that it is something related to the WordPress only because WP use global variables under the hood and I didn't want to use some prefix WP related, even if it is also for WordPress I never like prefixing my code with something related to a word that contains some correlation with it.

Table Of Contents

• Installation
• Introduction
• Basic Usage
• Advanced Usage
• Contributing
• License
• Credits

Installation

The best way to use this package is through Composer:

This package adheres to the SemVer specification and will be fully backward compatible between minor versions.

Introduction

Welcome to the documentation for ItalyStrap Event! In this introductory section, we will provide you with an overview of event-driven programming in the context of PHP development, WordPress and highlight the benefits of adopting this approach.

Event-Driven Programming: An Overview

Event-driven programming is a paradigm widely used in software development to handle reactive scenarios and manage interactions within a software system. It revolves around the concept of events, which represent specific occurrences or interactions.

In event-driven programming, software components (listeners or subscribers) register their interest in specific events and define how they should respond when those events occur. This decoupled and reactive architecture promotes modularity, flexibility, and maintainability in complex applications. Advantages of Event-Driven Programming

Event-driven programming offers several advantages that make it a valuable approach in various software development contexts:

1. Loose Coupling

Events act as communication channels between different parts of a system, allowing them to interact without tight dependencies. This loose coupling enhances code reusability and promotes the separation of concerns.

2. Scalability

Event-driven systems can effectively handle a large number of concurrent events, ensuring that the system remains responsive and adaptable to varying workloads.

3. Flexibility

Event-driven architectures are flexible and extensible. New functionality can be added by introducing new events and listeners without major changes to existing code.

4. Testability

Isolating event listeners allows for easier unit testing, as you can focus on testing individual components without the need for complex integration testing.

In the following sections of this documentation, we will delve deeper into the specifics of event-driven programming within the PHP ecosystem. We will explore how to work with events in WordPress, the core APIs for event handling, and how to seamlessly integrate the PSR-14 standard into your projects.

Let's continue our journey into the world of event-driven programming!

How an Event-Driven System Works

In this section, we'll provide an overview of how an event-driven system operates, explaining fundamental concepts, highlighting key components, and offering examples of common use cases for event-driven systems.

Understanding Event-Driven Programming

Event-driven programming is a software architecture that relies on events to trigger and manage the flow of a program. Here are some key concepts to grasp:

Events

Events represent specific occurrences or interactions within a system. They serve as signals or notifications that something has happened or needs attention. Events can range from user actions (e.g., button clicks) to system-generated notifications (e.g., data updates).

Event Handlers (Listeners)

Event handlers, often referred to as listeners or subscribers, are components responsible for responding to specific events. These listeners register their interest in particular events and execute predefined actions when those events occur.

Event Loop

The event loop is a fundamental part of event-driven systems. It continuously monitors for events and dispatches them to the appropriate event handlers. The loop ensures that events are processed in the order they occur, providing a responsive and non-blocking execution environment.

Key Components of an Event-Driven System

An event-driven system typically consists of the following components:

1. Events

Events define what can happen in the system and encapsulate relevant data associated with those occurrences.

2. Event Handlers (Listeners)

Event handlers, or listeners, respond to specific events by executing the corresponding actions or functions.

3. Event Loop

The event loop manages the flow of events, ensuring they are dispatched to the correct listeners.

4. Dispatcher

The dispatcher is responsible for coordinating the dispatch of events to their respective listeners. It acts as the central hub for event handling.

Common Use Cases for Event-Driven Systems

Event-driven systems are versatile and find applications in various domains. Here are some common use cases:

1. User Interfaces

Graphical user interfaces (GUIs) often rely on event-driven architectures to respond to user interactions such as button clicks, mouse movements, and keyboard inputs.

2. Real-Time Applications

Systems requiring real-time processing, such as online games, chat applications, and financial trading platforms, benefit from event-driven designs to ensure responsiveness.

3. Notifications and Alerts

Event-driven systems are well-suited for delivering notifications and alerts based on specific triggers or conditions.

4. IoT (Internet of Things)

IoT applications use event-driven principles to manage and process data generated by connected devices and sensors.

In the upcoming sections, we'll explore how event-driven programming is implemented in WordPress, dive into the core APIs for event handling, and demonstrate how to seamlessly integrate the PSR-14 standard into your projects.

Let's continue our journey into the world of event-driven programming!

How the WordPress Event System Works: Core APIs

In this section, we will dive into the core APIs used for event handling in WordPress. These APIs are essential for managing actions and filters, which serve as the building blocks of WordPress event-driven architecture. Unfortunately WordPress Event API use global variables under the hood, and this is a bad practice, but we can't do anything about it because WordPress will never change this, so we need to live with it and close our nose.

Actions and Filters

Actions

Actions in WordPress are events triggered at specific points during the execution of a request. Actions are instrumental for executing side effects or custom code at predefined moments within the WordPress lifecycle.

Actions do not return any values; instead, they serve as a signal for event handlers to perform tasks. When an action is fired, all attached action handlers (known as "action hooks") are executed sequentially.

Example of dispatching a simple action event (hook) without any arguments in WordPress:

And here the same event as above but with arguments this time:

Here, 'my_custom_action' represents the event name or hook. WordPress provides numerous predefined action hooks that developers can leverage to extend and customize the platform. To naming a few registered in the core:

• init
• wp_loaded
• admin_init
• admin_menu
• and so on...

Filters

Filters in WordPress are events similar to actions but with an important distinction: filters allow modification of data before it is used elsewhere in the system. Filters are used when you want to modify a value, content, or data passed through the filter (yes, you could also do this with actions, but I will talk about it later).

Filters return a modified or unaltered value, always, and multiple filter handlers (listener) can be applied in sequence as you can do with actions. Filters are widely used for customizing and manipulating data within WordPress.

Example of defining a filter hook and applying a filter:

Here, 'my_custom_filter' denotes the filter's event name or hook. WordPress allows developers to create their custom filters in addition to utilizing predefined filters.

Understanding the concept of hook/event names is crucial when working with actions and filters in WordPress. Event names serve as identifiers for specific points in the execution flow where custom code can be attached. Developers can use both WordPress-defined hooks and create custom hooks to extend and customize WordPress functionality.

So to remember actions and filters are mostly the same thing, and they are the dispatcher of the event system in WordPress.

WordPress use string as event name and in the WordPress documentation they are called hooks.

Dangerous things to know about dispatching actions and filters: Never ever dispatch an event inside a constructor of a class, this is a very bad practice and if you do that you are a bad developer.

🆙

Basic Usage

The \ItalyStrap\Event\GlobalDispatcher::class, \ItalyStrap\Event\GlobalOrderedListenerProvider::class and \ItalyStrap\Event\GlobalState::class are wrappers around the WordPress Plugin API

The \ItalyStrap\Event\Dispatcher::class and \ItalyStrap\Event\GlobalOrderedListenerProvider::class implement the PSR-14 Event Dispatcher.

Simple example for actions

Simple example for filters

Ok, so, for now it is very straightforward, you will use it like you use the WordPress Plugin API but more OOP oriented, you can inject the GlobalDispatcher::class or GlobalOrderedListenerProvider::class into yours classes.

The SubscriberRegister

What about the Subscriber Register? Here a simple example:

A subscriber is a class that implements the ItalyStrap\Event\SubscriberInterface::class interface and could be the listener itself or a class wrapper that delegates the execution of the method on certain event to the class it wraps.

The ItalyStrap\Event\SubscriberInterface::getSubscribedEvents() must return an iterable like those:

In case the subscriber has a lot of events to subscribe it is better to separate the business logic from the subscriber in another class and then use the subscriber to do the registration of the other class like this:

This library is similar to the Symfony Event Dispatcher

🆙

Advanced Usage

If you want more power you can use the Empress library with this library The benefit is that now you can do auto-wiring for your application, lazy loading you listener/subscriber and so on.

Lazy Loading a subscriber

To lazy load a subscriber you can simply add in the AurynConfig configuration a new value for proxy, see the example below:

Remember that the proxy version of an object is a "dumb" object that do nothing until you call some method, and the real object will be executed, this is useful for run code only when you need it to run.

Example with pseudocode;

You can find more information about the Empress\AurynConfig here You can find an implementation in the ItalyStrap Theme Framework

TODO https://inpsyde.com/en/remove-wordpress-hooks/

🆙

Contributing

All feedback / bug reports / pull requests are welcome.

🆙

License

Copyright (c) 2019 Enea Overclokk, ItalyStrap

This code is licensed under the MIT.

🆙

Credits

For the Event implementation

• Carl Alexander
• Carl Alexander

For the PsrDispatcher implementation

• Symfony
• Larry Garfield
• Timothy Jacobs