CakeDC Blog

This article is part of the CakeDC Advent Calendar 2024 (December 23rd 2024) Scott Wlaschin, a well known figure in the functional programming community, introduced the Railway Oriented Programming (ROP) pattern in his presentations and blog posts. His innovative approach to error handling has revolutionized how developers think about managing failures in their applications. Drawing inspiration from railway switches and tracks, Wlaschin created a metaphor that makes complex functional programming concepts more accessible to mainstream developers.

The Two-Track Model

At its core, Railway Oriented Programming visualizes data flow as a railway system with two parallel tracks: the success track and the failure track. This metaphor provides an elegant way to understand how data moves through an application while handling both successful operations and errors. Unlike traditional error handling with try-catch blocks or null checks, ROP treats success and failure as equal citizens, each flowing along its own track. This approach eliminates the need for nested error checking and creates a more linear, maintainable flow of operations.

Understanding Track Combinations

The railway model introduces several types of functions based on how they handle inputs and outputs. The simplest is the one-track function (1-1), which operates only on successful values, similar to a straight railway track. These functions take a value and return a value, without any concept of failure. Next, we have switch functions (1-2), which are like railway switches that can direct our train (data) onto either the success or failure track. Finally, two-track functions (2-2) operate on both success and failure cases, similar to a railway section that handles trains on both tracks.

PHP Implementation

The PHP Railway Programming library provides a robust implementation of these railway concepts through its Railway and Result classes. The Result class serves as our basic switch mechanism, while the Railway class provides the fluent interface for chaining operations. This implementation brings the elegance of functional programming's error handling to the PHP ecosystem, making it accessible to developers working with traditional object-oriented codebases.

Core Operations in Railway Programming

The map operation transforms values on the success track without affecting the failure track. It's like having a maintenance station that only services trains on the success track, letting failed trains pass by untouched on the failure track. This operation is perfect for simple transformations that can't fail. Conceptually, it accepts a 1-1 function and returns a 2-2 function. The lift operation transforms a regular one-track function into a switch function. Think of it as installing a safety system on a regular railway track - the function can now handle both success and failure cases. When we lift a function, we're essentially wrapping it in error handling capability, allowing it to participate in our two-track system. Conceptually, it accepts a 1-1 function and returns a 1-2 function. The bind operation is perhaps the most fundamental concept in ROP. It takes a switch function and adapts it to work with our two-track system. Imagine a railway junction where tracks can merge and split - bind ensures that success values continue on the success track while failures are automatically routed to the failure track. This operation is crucial for chaining multiple operations together while maintaining proper error handling. Conceptually, it accepts a switch 1-2 function and returns a 2-2 function. The tee operation is like a railway observation post - it allows us to perform side effects (like logging or monitoring) without affecting the train's journey on either track. It's particularly useful for debugging or adding analytics without disrupting the main flow of operations. Conceptually, it is a dead function that bypass the success or failure track. The tryCatch acts as a special kind of switch that can catch derailments (exceptions) and route them to the failure track. It's essential for integrating traditional try-catch error handling into our railway system, making it compatible with existing code that might throw exceptions. Conceptually, it accepts a 1-1 function and convert it into a 1-2 function. The plus and unite combinators are like complex railway junctions that can combine multiple tracks. Plus allows parallel processing of two separate railways, combining their results according to custom rules, and conceptually it accepts two 1-2 functions and returns a 1-2 function. The unite joins two railways sequentially, taking the result of the second railway if the first one succeeds. It conceptually accepts two 1-2 functions and join them into a 1-2 function. The doubleMap operation is a special kind of switch function that can handle both success and failure cases. It's like having a maintenance station that can service trains on both tracks, allowing us to transform values on both tracks without affecting the other. Conceptually, it accepts a 1-1 function and returns a 2-2 function.

Result Monad

The Result is a type that can be used to represent the result of a computation that can either succeed or fail. It is used for representing the computation in railway oriented programming flow.

Pattern matching

Pattern matching is a technique used to match the result of a computation against a set of patterns. It is used to extract the value of the result or handle the error case. Pattern matching in PHP Railway implementation serves as the final resolver for the two-track system, providing a clean way to extract values from either the success or failure track. The Railway::match method takes two callback functions: one for handling successful results and another for handling failures. This approach eliminates the need for manual checking of the Railway's state and provides a type-safe way to access the final values. In practical PHP applications, pattern matching becomes useful when we need to transform our Railway result into concrete actions or responses. For instance, when working with web frameworks, we can use pattern matching to either return a success response with the processed data or handle errors by throwing exceptions or returning error messages. This is more elegant than traditional conditional statements because it forces us to handle both cases explicitly and keeps the success and failure handling code clearly separated.

Practical Implementation: Room Reservation System

Let's explore a practical implementation of Railway Oriented Programming through a hotel room reservation system that we described in the Testing DCI with Behavior-Driven Development article. This example demonstrates how ROP can elegantly handle complex business processes with multiple potential failure points.

System Components

The reservation system consists of three main components:

1. ReservationData Context

It acts as an immutable data container that holds all necessary information about a reservation, including room details, guest information, check-in/out dates, and various state data. The immutability is ensured through a withState method that creates new instances when state changes are needed. namespace App\Reservation; use Cake\I18n\DateTime; class ReservationData { public function __construct( public readonly array $room, public readonly array $primaryGuest, public readonly array $additionalGuests, public readonly DateTime $checkIn, public readonly DateTime $checkOut, private array $state = [] ) {} public function withState(string $key, mixed $value): self { $clone = clone $this; $clone->state[$key] = $value; return $clone; } public function getState(string $key): mixed { return $this->state[$key] ?? null; } }

2. ReservationOperations

This class contains all the core business operations for the reservation process. Each operation is designed to work within the railway pattern, either returning successful results or failing gracefully. The operations include:

• Availability validation and price calculation
• Reservation creation in the database
• Email confirmation sending
• Loyalty points management
• Audit logging

namespace App\Reservation; use Cake\Mailer\Mailer; use ROP\Railway; use Cake\ORM\TableRegistry; class ReservationOperations { public static function validateAvailability(ReservationData $data): Railway { $reservationsTable = TableRegistry::getTableLocator()->get('Reservations'); $existingReservation = $reservationsTable->find() ->where([ 'room_id' => $data->room['id'], 'status !=' => 'cancelled', ]) ->where(function ($exp) use ($data) { return $exp->or([ function ($exp) use ($data) { return $exp->between('check_in', $data->checkIn, $data->checkOut); }, function ($exp) use ($data) { return $exp->between('check_out', $data->checkIn, $data->checkOut); } ]); }) ->first(); if ($existingReservation) { return Railway::fail("Room is not available for selected dates"); } $totalGuests = count($data->additionalGuests) + 1; if ($totalGuests > $data->room['capacity']) { return Railway::fail( "Total number of guests ({$totalGuests}) exceeds room capacity ({$data->room['capacity']})" ); } $basePrice = $data->room['base_price'] * $data->checkIn->diffInDays($data->checkOut); $discount = match($data->primaryGuest['loyalty_level']) { 'gold' => 0.1, 'silver' => 0.05, default => 0 }; $finalPrice = $basePrice * (1 - $discount); return Railway::of($data->withState('total_price', $finalPrice)); } public static function createReservation(ReservationData $data): ReservationData { $reservationsTable = TableRegistry::getTableLocator()->get('Reservations'); $reservation = $reservationsTable->newEntity([ 'room_id' => $data->room['id'], 'primary_guest_id' => $data->primaryGuest['id'], 'check_in' => $data->checkIn, 'check_out' => $data->checkOut, 'status' => 'confirmed', 'total_price' => $data->getState('total_price'), 'reservation_guests' => array_map( fn($guest) => ['guest_id' => $guest['id']], $data->additionalGuests ), ]); if (!$reservationsTable->save($reservation)) { throw new \RuntimeException('Could not save reservation'); } return $data->withState('reservation_id', $reservation->id); } public static function logReservation(ReservationData $data): ReservationData { TableRegistry::getTableLocator()->get('Reservations')->logOperation( // ... ); return $data; } public static function sendConfirmationEmail(ReservationData $data): Railway { $result = rand(0,10); return $result > 2 ? Railway::of($data) : Railway::fail('Failed to send confirmation email'); } public static function updateGuestLoyaltyPoints(ReservationData $data): ReservationData { // ... return $data; } }

3. ReservationController

This class acts as the controller for the reservation system. It handles the HTTP request, validates the input, and orchestrates the reservation process using the Railway class. The controller uses the ReservationOperations class to perform the necessary operations and handles the result of each operation using the Railway::match method. namespace App\Reservation; use ROP\Railway; class ReservationController { public function add() { $Rooms = $this->fetchTable('Rooms'); $Guests = $this->fetchTable('Guests'); $rooms = $Rooms->find('list')->where(['status' => 'available']); $guests = $Guests->find('list'); $this->set(compact('rooms', 'guests')); if ($this->request->is('post')) { try { $room = $Rooms->get($this->request->getData('room_id'))->toArray(); $primaryGuest = $Guests->get($this->request->getData('primary_guest_id'))->toArray(); $additionalGuests = []; if ($this->request->getData('additional_guest_ids')) { $additionalGuests = $Guests->find() ->where(['id IN' => $this->request->getData('additional_guest_ids')]) ->all() ->map(fn($guest) => $guest->toArray()) ->toArray(); } $data = new ReservationData( room: $room, primaryGuest: $primaryGuest, additionalGuests: $additionalGuests, checkIn: new DateTime($this->request->getData('check_in')), checkOut: new DateTime($this->request->getData('check_out')) ); $connection = $this->fetchTable('Reservations')->getConnection(); return $connection->transactional(function($connection) use ($data) { $result = ReservationOperations::validateAvailability($data) // First validate and calculate price ->map(fn($data) => $data->withState('reservation_time', time())) // Create reservation with error handling ->tryCatch(fn($data) => ReservationOperations::createReservation($data)) // Send confirmation email (might fail) ->bind(fn($data) => ReservationOperations::sendConfirmationEmail($data)) // Log the reservation (with error handling) ->tryCatch(fn($data) => ReservationOperations::logReservation($data)) // Update room status (simple transformation) ->map(fn($data) => $data->withState('room_status', 'occupied')) // Calculate loyalty points (simple transformation) ->map(fn($data) => $data->withState( 'loyalty_points', floor($data->getState('total_price') * 0.1) )) // Update guest loyalty points (with error handling) ->tryCatch(fn($data) => ReservationOperations::updateGuestLoyaltyPoints($data)) // Log all operations for audit ->tee(fn($data) => error_log(sprintf( "Reservation completed: %s, Points earned: %d", $data->getState('reservation_id'), $data->getState('loyalty_points') ))); return $result->match( success: function($data) { $this->Flash->success(__('Reservation confirmed! Your confirmation number is: {0}', $data->getState('reservation_id') )); return $this->redirect(['action' => 'view', $data->getState('reservation_id')]); }, failure: function($error) { if ($error instanceof \Exception) throw $error; throw new \RuntimeException($error); } ); }); } catch (\Exception $e) { $this->Flash->error(__('Unable to complete reservation: {0}', $e->getMessage())); } } } }

The Railway Flow

The reservation process showcases several key aspects of Railway Oriented Programming:

1. Input Validation: The process begins with validating room availability and guest capacity, demonstrating how early failures can be handled gracefully.
2. State Transformation: Throughout the process, the ReservationData object is transformed through various states while maintaining immutability.
3. Error Handling: Each step can potentially fail, but the railway pattern keeps the error handling clean and predictable.
4. Transaction Management: The entire process is wrapped in a database transaction, showing how ROP can work with traditional database operations.
5. Side Effects: The pattern handles side effects (like sending emails and logging) in a controlled manner through the tee operation.

The sequence diagram illustrates how the Railway pattern creates a clear separation between success and failure paths, making it easier to reason about the system's behavior. This implementation shows that Railway Oriented Programming is not just a theoretical concept but a practical approach to handling complex business processes in real-world applications. sequenceDiagram participant C as Controller participant DB as Database participant E as Email participant R as Railway Track Note over R: Success Track ✅ Note over R: Failure Track ❌ C->>DB: Check Room Availability alt Room not available DB-->>R: ❌ "Room not available" R-->>C: Railway::fail else Room available DB-->>R: ✅ Room data Note over R: Validate Guest Count alt Exceeds capacity R-->>C: ❌ Railway::fail("Exceeds capacity") else Guest count OK R-->>C: ✅ Calculate price & set state C->>DB: Creating Reservation alt Save successful DB-->>R: ✅ reservation_id C->>E: Send Confirmation alt Email sent E-->>R: ✅ Continue else Email failed E-->>R: ❌ "Failed to send email" R-->>C: Railway::fail end C->>DB: Adding Audit Log DB-->>R: ✅ Continue C->>DB: Updating Loyalty Points alt Update successful DB-->>R: ✅ Final success R-->>C: Railway::of(data) else Update failed DB-->>R: ❌ "Failed to update points" R-->>C: Railway::fail end else Save failed DB-->>R: ❌ "Could not save reservation" R-->>C: Railway::fail end end end This room reservation system demonstrates several key benefits of Railway Oriented Programming:

1. Clarity: The code clearly shows the flow of operations and potential failure points, making it easier to understand and maintain.
2. Robustness: Error handling is comprehensive and consistent throughout the entire process.
3. Maintainability: New steps can be easily added to the reservation process by extending the railway chain.
4. Transaction Safety: The pattern works seamlessly with database transactions, ensuring data consistency.
5. Testability: Each operation is isolated and can be tested independently, while the entire flow can be tested as a unit.

This example serves as a blueprint for implementing similar patterns in other business domains where complex workflows and error handling are required. It demonstrates how functional programming concepts can be successfully applied in a traditionally object-oriented environment like PHP.

Demo Project for Article

The examples used in this article are located at https://github.com/skie/cakephp-dci/tree/3.0.0 and available for testing. The controller code is located at src/Controller/RopReservationsController.php.

Conclusion

Railway Oriented Programming represents a paradigm shift in error handling, moving away from imperative try-catch blocks toward a more functional, flow-based approach. By visualizing our program as a railway system, we gain a powerful metaphor for understanding and managing the complexity of error handling in our applications. The PHP implementation of ROP brings these concepts to the PHP community, enabling developers to write more maintainable, readable, and robust code. This article is part of the CakeDC Advent Calendar 2024 (December 23rd 2024)

This article is part of the CakeDC Advent Calendar 2024 (December 22nd 2024) Authorization can become a complex topic. If you go over the options described in the CakePHP Book, https://book.cakephp.org/authorization/3/en/index.html and the specific tutorial https://book.cakephp.org/5/en/tutorials-and-examples/cms/authorization.html, you'll see that there are options to define the authorization in a very flexible way. In CakePHP, the Authorization Plugin will allow you to define subjects of authorization, entities that want to get access to one of these subjects, and rules to determine if the entities can have access to a given subject. Many CakePHP applications coming from versions 1,2,3 don't require a lot of flexibility because they define:

• Subject: a plugin/prefix/Controller/action, like a "url" in our site, for example: "/admin/users/add"
• Entity: a logged in user, or a guest user who is not logged in yet. Usually we'll group the users in a role, to allow assigning permissions per role
• Rule: a function, returning true or false

In these cases, we can build an authorization table, like URL Role CanAccess? /admin/users/index admins yes /admin/users/index users no ... To apply these concepts in you CakePHP Application, you can use existing plugins like:

• https://github.com/CakeDC/users
• https://github.com/dereuromark/cakephp-tinyauth

But, following our spirit of simplicity, let's imagine you've implemented the CakePHP CMS Tutorial https://book.cakephp.org/5/en/tutorials-and-examples.html. Or, you can clone the project from here: https://github.com/cakephp/cms-tutorial.

• Clone project git clone https://github.com/cakephp/cms-tutorial.git
• Create config/app_local.php file with your datasource configuration, for example this one https://gist.github.com/steinkel/c28ffb6dfe36294e6d4e378ad71d564a
• Run migrations bin/cake migrations migrate
• bin/cake server
• Enjoy, visit http://localhost:8765

In this case, to enable url base authentication we would need to change:

• composer require cakedc/auth
• Update the AuthorizationService configuration to map the request object with a collection of policies

// src/Application::getAuthorizationService public function getAuthorizationService(ServerRequestInterface $request): AuthorizationServiceInterface { $map = new MapResolver(); $map->map( ServerRequest::class, new CollectionPolicy([ SuperuserPolicy::class, new RbacPolicy([ [ 'role' => '*', 'controller' => 'Pages', 'action' => 'display', ], // other rules // the rules could be stored in a configuration file or database ]), ]) ); $orm = new OrmResolver(); $resolver = new ResolverCollection([ $map, $orm, ]); return new AuthorizationService($resolver); }

• The last piece to this approach would be adding the RequestAuthorizationMiddleware:

// src/Application::middleware public function middleware($middlewareQueue): \Cake\Http\MiddlewareQueue { $middlewareQueue // ... ->add(new AuthorizationMiddleware($this)) ->add(new RequestAuthorizationMiddleware());

How will it work?

For each request to your application, the RequestAuthorizationMiddleware will trigger an authorization check, looking for a Policy in the MapResolver. We'll check first if the user has the column is_superuser set as true, and if not, we'll use the Rbac to check if the user can access the given URL, using the routing parameters. The Rbac class provides a lot of flexibility to configure the rules, see https://github.com/CakeDC/auth/blob/8.next-cake5/Docs/Documentation/Rbac.md. Note: the users table included in the CMS Tutorial does not include a role column. If you want to define roles, you would need to add it using a Migration.

Recap

We've used the cms tutorial application from the CakePHP Book to implement a Request Authorization Rbac policy for simple applications looking for a way to determine if a given URL can be accessed by a user role. This article is part of the CakeDC Advent Calendar 2024 (December 22nd 2024)

This article is part of the CakeDC Advent Calendar 2024 (December 21th 2024) The CakeDC Search Filter plugin is a powerful tool for CakePHP applications that provides advanced search functionality with a modern, user-friendly interface. It combines backend flexibility with a Vue.js-powered frontend to create dynamic search filters. Key features include:

• Dynamic filter generation based on database schema
• Multiple filter types for different data types
• Customizable search conditions
• Interactive Vue.js frontend
• AJAX-powered autocomplete functionality
• Seamless integration with CakePHP's ORM

Setup

1. Install the plugin using Composer: composer require cakedc/search-filter
2. Load the plugin in your application's src/Application.php: $this->addPlugin('CakeDC/SearchFilter');
3. Add the search element to your view inside search form: <?= $this->element('CakeDC/SearchFilter.Search/v_search'); ?>
4. Initialize the Vue.js application: <script> window._search.createMyApp(window._search.rootElemId) </script>

Filters

Filters are the user interface elements that allow users to interact with the search. The plugin provides several built-in filter types for different data scenarios:

1. BooleanFilter: For Yes/No selections $booleanFilter = (new BooleanFilter()) ->setCriterion(new BoolCriterion('is_active')) ->setLabel('Active Status') ->setOptions([1 => 'Active', 0 => 'Inactive']);
2. DateFilter: For date-based filtering $dateFilter = (new DateFilter()) ->setCriterion(new DateCriterion('created_date')) ->setLabel('Creation Date') ->setDateFormat('YYYY-MM-DD');
3. StringFilter: For text-based searches $stringFilter = (new StringFilter()) ->setCriterion(new StringCriterion('title')) ->setLabel('Title');
4. NumericFilter: For number-based filtering $numericFilter = (new NumericFilter()) ->setCriterion(new NumericCriterion('price')) ->setLabel('Price') ->setProperty('step', '0.01');
5. LookupFilter: For autocomplete-based filtering $lookupFilter = (new LookupFilter()) ->setCriterion(new LookupCriterion('user_id', $usersTable, new StringCriterion('name'))) ->setLabel('User') ->setLookupFields(['name', 'email']) ->setAutocompleteRoute(['controller' => 'Users', 'action' => 'autocomplete']);
6. MultipleFilter: For selecting multiple values $multipleFilter = (new MultipleFilter()) ->setCriterion(new InCriterion('category_id', $categoriesTable, new StringCriterion('name'))) ->setLabel('Categories') ->setProperty('placeholder', 'Select multiple options');
7. SelectFilter: For dropdown selections $selectFilter = (new SelectFilter()) ->setCriterion($manager->criterion()->numeric('status_id')) ->setLabel('Status') ->setOptions($this->Statuses->find('list')->toArray()) ->setEmpty('All Statuses');

Criteria Purpose and Usage

Criteria are the building blocks that define how filters operate on your data. They handle the actual query building and data filtering. Key criterion types include:

1. AndCriterion: Combines multiple criteria with AND logic
2. BoolCriterion: Handles boolean comparisons
3. StringCriterion: Handles string matching
4. DateCriterion: Manages date comparisons
5. DateTimeCriterion: Manages datetime comparisons
6. InCriterion: Handles in comparisons
7. LookupCriterion: Handles lookup comparisons
8. NumericCriterion: Handles numeric comparisons
9. OrCriterion: Combines multiple criteria with OR logic

Example of combining criteria: $complexCriterion = new OrCriterion([ new StringCriterion('title'), new StringCriterion('content') ]);

Filters Usage

Let's walk through a complete example of setting up filters in a controller. This implementation demonstrates how to integrate search filters with our htmx application from previous articles.

Controller Setup

First, we need to initialize the PlumSearch filter component in our controller: public function initialize(): void { parent::initialize(); $this->loadComponent('PlumSearch.Filter'); }

Implementing Search Filters

Here's a complete example of setting up filters in the controller's list method: // /src/Controller/PostsController.php protected function list() { $query = $this->Posts->find(); $manager = new Manager($this->request); $collection = $manager->newCollection(); $collection->add('search', $manager->filters() ->new('string') ->setConditions(new \stdClass()) ->setLabel('Search...') ); $collection->add('name', $manager->filters() ->new('string') ->setLabel('Name') ->setCriterion( new OrCriterion([ $manager->buildCriterion('title', 'string', $this->Posts), $manager->buildCriterion('body', 'string', $this->Posts), ]) ) ); $collection->add('created', $manager->filters() ->new('datetime') ->setLabel('Created') ->setCriterion($manager->buildCriterion('created', 'datetime', $this->Posts)) ); $viewFields = $collection->getViewConfig(); if (!empty($this->getRequest()->getQuery()) && !empty($this->getRequest()->getQuery('f'))) { $search = $manager->formatSearchData(); $this->set('values', $search); $this->Posts->addFilter('search', [ 'className' => 'Multiple', 'fields' => [ 'title', 'body', ] ]); $this->Posts->addFilter('multiple', [ 'className' => 'CakeDC/SearchFilter.Criteria', 'criteria' => $collection->getCriteria(), ]); $filters = $manager->formatFinders($search); $query = $query->find('filters', params: $filters); } $this->set('viewFields', $viewFields); $posts = $this->paginate($this->Filter->prg($query), ['limit' => 12]); $this->set(compact('posts')); }

Table Configuration

Enable the filterable behavior in your table class: // /src/Model/Table/PostsTable.php public function initialize(array $config): void { // ... $this->addBehavior('PlumSearch.Filterable'); }

View Implementation

In your view template, add the necessary assets and initialize the search filter: <!-- templates/Posts/index.php --> <?= $this->Html->css('CakeDC/SearchFilter.inline'); ?> <?= $this->Html->script('CakeDC/SearchFilter.vue3.js'); ?> <?= $this->Html->script('CakeDC/SearchFilter.main.js', ['type' => 'module']); ?> <?= $this->element('CakeDC/SearchFilter.Search/v_templates'); ?> <div id="search"> <?= $this->Form->create(null, [ 'id' => 'search-form', 'type' => 'get', 'hx-get' => $this->Url->build(['controller' => 'Posts', 'action' => 'index']), 'hx-target' => "#posts", ]); ?> <div id="ext-search"></div> <?= $this->Form->button('Search', ['type' => 'submit', 'class' => 'btn btn-primary']); ?> <?= $this->Form->end(); ?> </div> <script> window._search = window._search || {}; window._search.fields = <?= json_encode($viewFields) ?>; var values = null; <?php if (!empty($values)): ?> window._search.values = <?= json_encode($values) ?>; <?php else: ?> window._search.values = {}; <?php endif; ?> </script>

JavaScript Integration

Finally, add the necessary JavaScript to handle the search filter initialization and htmx interactions: <!-- /templates/Posts/index.php --> <script> function setupTable(reload) { if (reload) { setTimeout(function () { window._search.app.unmount() window._search.createMyApp(window._search.rootElemId) }, 20); } } document.addEventListener('DOMContentLoaded', function() { window._search.createMyApp(window._search.rootElemId) setupTable(false); htmx.on('htmx:afterRequest', (evt) => { setupTable(true); }) }); </script> The combination of CakePHP's search filter plugin with htmx provides a modern, responsive search experience with minimal JavaScript code.

Frontend Vue App Widgets

The plugin provides several Vue.js widgets for different filter types:

• SearchInput: For basic text input
• SearchInputNumericRange: For basic text input
• SearchSelect, Select2, SearchSelectMultiple: For dropdown selections
• SearchInputDate, SearchInputDateRange: For date picking
• SearchInputDateTime, SearchInputDateTimeRange: For datetime picking
• SearchLookupInput: For autocomplete functionality
• SearchMultiple: For multiple selections
• SearchSelectMultiple: For multiple selections

These widgets are automatically selected based on the filter type you define in your controller.

Custom Filters and Custom Widgets

The CakeDC Search Filter plugin can be extended with custom filters and widgets. Let's walk through creating a custom range filter that allows users to search between two numeric values.

Custom Filter Class

First, create a custom filter class that extends the AbstractFilter: // /src/Controller/Filter/RangeFilter.php <?php declare(strict_types=1); namespace App\Controller\Filter; use Cake\Controller\Controller; use CakeDC\SearchFilter\Filter\AbstractFilter; class RangeFilter extends AbstractFilter { protected array $properties = [ 'type' => 'range', ]; protected object|array|null $conditions = [ self::COND_BETWEEN => 'Between', ]; }

Custom Criterion Implementation

Create a criterion class to handle the range filtering logic: // /src/Model/Filter/Criterion/RangeCriterion.php <?php declare(strict_types=1); namespace App\Model\Filter\Criterion; use Cake\Database\Expression\QueryExpression; use Cake\ORM\Query; use CakeDC\SearchFilter\Filter\AbstractFilter; use CakeDC\SearchFilter\Model\Filter\Criterion\BaseCriterion; class RangeCriterion extends BaseCriterion { protected $field; public function __construct($field) { $this->field = $field; } public function __invoke(Query $query, string $condition, array $values, array $criteria, array $options): Query { $filter = $this->buildFilter($condition, $values, $criteria, $options); if (!empty($filter)) { return $query->where($filter); } return $query; } public function buildFilter(string $condition, array $values, array $criteria, array $options = []): ?callable { return function (QueryExpression $exp) use ($values) { if (!empty($values['from']) && !empty($values['to'])) { return $exp->between($this->field, $values['from'], $values['to']); } return $exp; }; } public function isApplicable($value, string $condition): bool { return !empty($value['from']) || !empty($value['to']); } }

Controller Integration

Update your controller to use the custom range filter: // /src/Controller/PostsController.php protected function list() { // ... $manager = new Manager($this->request); $manager->filters()->load('range', ['className' => RangeFilter::class]); $collection = $manager->newCollection(); $collection->add('id', $manager->filters() ->new('range') ->setLabel('Id Range') ->setCriterion($manager->buildCriterion('id', 'integer', $this->Posts)) ); // ... }

Custom Vue.js Widget

Create a custom Vue.js component for the range input. It consists of two parts, widget template and widget component: <!-- /templates/Posts/index.php --> <script type="text/x-template" id="search-input-range-template"> <span class="range-wrapper d-flex"> <input type="number" class="form-control value value-from" :name="'v[' + index + '][from][]'" v-model="fromValue" @input="updateValue" :placeholder="field.fromPlaceholder || 'From'" /> <span class="range-separator d-flex align-items-center">&nbsp;&mdash;&nbsp;</span> <input type="number" class="form-control value value-to" :name="'v[' + index + '][to][]'" v-model="toValue" @input="updateValue" :placeholder="field.toPlaceholder || 'To'" /> </span> </script> <script> const RangeInput = { template: "#search-input-range-template", props: ['index', 'value', 'field'], data() { return { fromValue: '', toValue: '', }; }, methods: { updateValue() { this.$emit('change-value', { index: this.index, value: { from: this.fromValue, to: this.toValue } }); } }, mounted() { if (this.value) { this.fromValue = this.value.from || ''; this.toValue = this.value.to || ''; } }, watch: { value(newValue) { if (newValue) { this.fromValue = newValue.from || ''; this.toValue = newValue.to || ''; } else { this.fromValue = ''; this.toValue = ''; } } } }; <script>

Component Registration

Register the custom widget in the Vue.js app. Implement the register function to register the custom widget, and the setupTable function to setup the table after a htmx request. // /templates/Posts/index.php function register(app, registrator) { app.component('RangeInput', RangeInput); registrator('range', function(cond, type) { return 'RangeInput';}); } function setupTable(reload) { if (reload) { setTimeout(function () { window._search.app.unmount() window._search.createMyApp(window._search.rootElemId, register) }, 20); } } document.addEventListener('DOMContentLoaded', function() { window._search.createMyApp(window._search.rootElemId, register) setupTable(false); htmx.on('htmx:afterRequest', (evt) => { setupTable(true); }) }); </script> This implementation creates a custom range filter that allows users to search for records within a specified numeric range. The filter consists of three main components:

1. A custom filter class (RangeFilter) that defines the filter type and conditions
2. A custom criterion class (RangeCriterion) that implements the filtering logic
3. A Vue.js component (RangeInput) that provides the user interface for entering range values
4. A registration function to register the custom widget, and the setupTable function to setup the table after a htmx request.

Demo Project for Article

The examples used in this article are located at https://github.com/skie/cakephp-htmx/tree/4.0.0 and available for testing.

Conclusion

The CakeDC Search Filter plugin provides a robust solution for implementing advanced search functionality in CakePHP applications. Its combination of flexible backend filtering and modern frontend components makes it an excellent choice for any CakePHP project. The plugin's extensibility allows for customization to meet specific project needs, while its built-in features cover most common search scenarios out of the box. Whether you need simple text searches or complex multi-criteria filtering, the Search Filter plugin offers the tools to build user-friendly search interfaces. This article is part of the CakeDC Advent Calendar 2024 (December 21th 2024)