CakeDC Blog

TIPS, INSIGHTS AND THE LATEST FROM THE EXPERTS BEHIND CAKEPHP

Streaming database results

Written by Jorge on December 17, 2024 •
150 VIEWS

This article is part of the CakeDC Advent Calendar 2024 (December 17th 2024)

This is a small tip related with an issue we fixed not so long ago. While executing a report, exporting the data as a csv file, we hit a max_memory issue. That's a very common issue when your tables grow bigger and the amount of data you need to export does not fit into the available memory for the PHP process.

In that case you have a couple options like:

Push the report generation to a background job, then send the result link via email
Work with ob_start(), flush() etc

But today we are going to show a way to do it using CakePHP builtin methods.

Let's imagine we are exporting a big Users table like:

$users = $this->fetchTable('Users')->find();
foreach ($users as $user) {
   // handle the user row
}

Causing a 500 error due to a lack of memory to store all the users resultset.

And we don't want to process anything in the background, we just want the user to "wait" for the result being generated (note this also could be an issue if it's too long).

We could use the following approach in our controller:

return $this->response
        ->withType('text/csv') // or other formats, in case of xml, json, etc
        ->withDownload('my-big-report.csv')
        ->withBody(new \Cake\Http\CallbackStream(function () {
            $users = $this->fetchTable('Users')->find()
                ->disableBufferedResults()
                ->disableHydration()
                ->toArray();
            $outstream = fopen("php://output", 'w');
            foreach ($users as $user) {
                fputcsv($outstream, $row);
            }
        }));

A note about the solution

disableBufferedResults does not work for all datasources due to a limitation in PDO. It works for MySQL.
- In case your are using a not compatible datasource, you'll need to paginate the query manually to get the results in chunks

So, using this approach we are paying time (more queries to the database, longer response time, user waiting) for RAM. Depending on your case, it could be a fair tradeoff.

Marc (@ravage84) suggested in slack to also take a look at https://github.com/robotusers/cakephp-chunk too for a way to chunk the results of a query, processing them in a memory efficient way.

This article is part of the CakeDC Advent Calendar 2024 (December 17th 2024)

Latest articles

45 Views

CakeDC Search Filter Plugin

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

Install the plugin using Composer: composer require cakedc/search-filter
Load the plugin in your application's src/Application.php: $this->addPlugin('CakeDC/SearchFilter');
Add the search element to your view inside search form: <?= $this->element('CakeDC/SearchFilter.Search/v_search'); ?>
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:

BooleanFilter: For Yes/No selections $booleanFilter = (new BooleanFilter()) ->setCriterion(new BoolCriterion('is_active')) ->setLabel('Active Status') ->setOptions([1 => 'Active', 0 => 'Inactive']);
DateFilter: For date-based filtering $dateFilter = (new DateFilter()) ->setCriterion(new DateCriterion('created_date')) ->setLabel('Creation Date') ->setDateFormat('YYYY-MM-DD');
StringFilter: For text-based searches $stringFilter = (new StringFilter()) ->setCriterion(new StringCriterion('title')) ->setLabel('Title');
NumericFilter: For number-based filtering $numericFilter = (new NumericFilter()) ->setCriterion(new NumericCriterion('price')) ->setLabel('Price') ->setProperty('step', '0.01');
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']);
MultipleFilter: For selecting multiple values $multipleFilter = (new MultipleFilter()) ->setCriterion(new InCriterion('category_id', $categoriesTable, new StringCriterion('name'))) ->setLabel('Categories') ->setProperty('placeholder', 'Select multiple options');
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:

AndCriterion: Combines multiple criteria with AND logic
BoolCriterion: Handles boolean comparisons
StringCriterion: Handles string matching
DateCriterion: Manages date comparisons
DateTimeCriterion: Manages datetime comparisons
InCriterion: Handles in comparisons
LookupCriterion: Handles lookup comparisons
NumericCriterion: Handles numeric comparisons
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. Figure 1-1

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:

A custom filter class (RangeFilter) that defines the filter type and conditions
A custom criterion class (RangeCriterion) that implements the filtering logic
A Vue.js component (RangeInput) that provides the user interface for entering range values
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)

Written by Yevgeny on December 21, 2024

61 Views

5 CakePHP security tips

This article is part of the CakeDC Advent Calendar 2024 (December 20th 2024) We all know the importance of security in our sites, so here we have 5 quick tips that can improve the security of your site quickly:

Ensure all cookies are configured for security
- They say they are going away soon... but meanwhile... keep them secure. ALL the cookies produced in your site, unless you have very specific reasons, should be configured as Secure, HttpOnly, SameSite Strict. See https://book.cakephp.org/5/en/controllers/request-response.html#creating-cookies when creating cookies. Here's a code snippet for your session cookie:

// config/app.php
'Session' => [
        // .. other configurations
        'cookie' => 'CUSTOM_NAME_FOR_YOUR_SESSION_COOKIE',
        'ini' => [
            'session.cookie_secure' => true,
            'session.cookie_httponly' => true,
            'session.cookie_samesite' => 'Strict',
        ],
    ],

Audit your dependencies
- Both backend and frontend dependencies could be impacted by security issues. In the case of the backend, you can have a quick look by running composer audit. In case of issues, you'll see an output similar to:

$ composer audit
Found 7 security vulnerability advisories affecting 4 packages:
+-------------------+----------------------------------------------------------------------------------+
| Package           | composer/composer                                                                |
| CVE               | CVE-2024-35241                                                                   |
| Title             | Composer has a command injection via malicious git branch name                   |
| URL               | https://github.com/advisories/GHSA-47f6-5gq3-vx9c                                |
| Affected versions | >=2.3,<2.7.7|>=2.0,<2.2.24                                                       |
| Reported at       | 2024-06-10T21:36:32+00:00                                                        |
+-------------------+----------------------------------------------------------------------------------+

Use CSRF
- CSRF attacks https://owasp.org/www-community/attacks/csrf can be mitigated by using the CakePHP CSRF Middleware. Check your code, usually /src/Application.php for the Middleware:

// in src/Application::middleware()

    // Cross Site Request Forgery (CSRF) Protection Middleware
    // https://book.cakephp.org/4/en/security/csrf.html#cross-site-request-forgery-csrf-middleware
    ->add(new CsrfProtectionMiddleware([
        'httponly' => true,
    ]));

Enforce HTTPS
- Ensure your live applications are enforcing HTTPS to prevent downgrading to HTTP. You can handle that in a number of ways, for example using your webserver configuration, or a Proxy. If you want to handle it via CakePHP builtins, add

// in src/Application::middleware()

    ->add(new HttpsEnforcerMiddleware([
        'hsts' => [
            'maxAge' => 10,
            'includeSubDomains' => true,
            'preload' => false, // use preload true when you are sure all subdomains are OK with HTTPS
        ],
    ]))

Implement security headers
- It's an additional layer of defense agains attacks, like XSS https://owasp.org/www-community/attacks/xss/ and others

// in src/Application::middleware()
    $securityHeaders = (new SecurityHeadersMiddleware())
        ->setReferrerPolicy() // limit referrer info leaked
        ->setXFrameOptions() // mitigates clickjacking attacks
        ->noOpen() // don't save file in downloads auto
        ->noSniff(); // mitigates mime type sniffing
    $middlewareQueue
        // ...
        ->add($securityHeaders)
        // ...

This is just a quick example of 5 changes in code you could apply today to improve your CakePHP website security. Keep your projects safe! This article is part of the CakeDC Advent Calendar 2024 (December 20th 2024)

Written by Jorge on December 20, 2024

111 Views

Testing DCI with Behavior-Driven Development

This article is part of the CakeDC Advent Calendar 2024 (December 19th 2024) In our previous article, we explored the Data-Context-Interaction (DCI) pattern and its implementation in PHP using CakePHP. We demonstrated how DCI helps separate data structures from their runtime behaviors through roles and contexts, using a money transfer system as an example. Now, let's dive into testing DCI implementations using Behavior-Driven Development (BDD) with Behat, exploring a practical hotel room reservation system.

Room Reservation System Overview

The room reservation system demonstrates DCI's power in managing complex business rules and interactions. In this system, rooms and guests are our core data objects, while the reservation process involves multiple roles and behaviors. A room can be reservable under certain conditions (availability, capacity), and guests can have different privileges based on their loyalty levels. The reservation context orchestrates these interactions, ensuring business rules are followed and the system maintains consistency.

Database Structure

The database schema reflects our domain model with proper relationships between entities: erDiagram rooms { id integer PK number varchar(10) type varchar(50) capacity integer base_price decimal status varchar(20) created datetime modified datetime } guests { id integer PK name varchar(100) email varchar(100) phone varchar(20) loyalty_level varchar(20) created datetime modified datetime } reservations { id integer PK room_id integer FK primary_guest_id integer FK check_in date check_out date status varchar(20) total_price decimal created datetime modified datetime } reservation_guests { id integer PK reservation_id integer FK guest_id integer FK created datetime } audit_logs { id integer PK model varchar(100) foreign_key integer operation varchar(50) data json created datetime } reservations ||--|| rooms : "has" reservations ||--|| guests : "primary guest" reservation_guests }|--|| reservations : "belongs to" reservation_guests }|--|| guests : "includes" audit_logs }|--|| reservations : "logs" Key aspects of this schema:

Rooms table stores physical hotel rooms with their properties
Guests table maintains customer information including loyalty status
Reservations table handles booking details with pricing
Reservation_guests enables multiple guests per reservation
Audit_logs provides system-wide operation tracking

classDiagram class Room { +String number +String type +Integer capacity +Decimal basePrice +String status } class Guest { +String name +String email +String phone +String loyaltyLevel } class Reservation { +Room room +Guest primaryGuest +Date checkIn +Date checkOut +String status +Decimal totalPrice } class ReservationGuest { +Reservation reservation +Guest guest } Reservation --> Room Reservation --> Guest ReservationGuest --> Reservation ReservationGuest --> Guest The class diagram above shows our core data model. Each entity has specific attributes that define its state, but the interesting part comes with how these objects interact during the reservation process. Let's examine how DCI roles enhance this basic structure: classDiagram class ReservableRoom { +isAvailableForDates(checkIn, checkOut) +canAccommodateGuests(guestCount) +calculatePrice(checkIn, checkOut) } class ReservingGuest { +canMakeReservation() +calculateDiscount(basePrice) } class RoomReservationContext { +Room room +Guest primaryGuest +List~Guest~ additionalGuests +Date checkIn +Date checkOut +execute() } Room ..|> ReservableRoom : implements Guest ..|> ReservingGuest : implements RoomReservationContext --> ReservableRoom : uses RoomReservationContext --> ReservingGuest : uses The reservation process involves multiple interactions between objects, each playing their specific roles. The sequence diagram below illustrates how these components work together: sequenceDiagram participant RC as ReservationsController participant RRC as RoomReservationContext participant R as Room participant G as Guest participant RR as ReservableRoom participant RG as ReservingGuest participant DB as Database RC->>RRC: new RoomReservationContext(room, guest, dates) activate RRC RRC->>R: addRole('ReservableRoom') RRC->>G: addRole('ReservingGuest') RC->>RRC: execute() RRC->>R: isAvailableForDates(checkIn, checkOut) R->>RR: isAvailableForDates(checkIn, checkOut) RR-->>RRC: true/false alt Room is available RRC->>R: canAccommodateGuests(guestCount) R->>RR: canAccommodateGuests(guestCount) RR-->>RRC: true/false alt Can accommodate guests RRC->>G: canMakeReservation() G->>RG: canMakeReservation() RG-->>RRC: true/false alt Guest can make reservation RRC->>R: calculatePrice(checkIn, checkOut) R->>RR: calculatePrice(checkIn, checkOut) RR-->>RRC: basePrice RRC->>G: calculateDiscount(basePrice) G->>RG: calculateDiscount(basePrice) RG-->>RRC: discount RRC->>DB: save reservation DB-->>RRC: success else RRC-->>RC: throw GuestCannotReserveException end else RRC-->>RC: throw CapacityExceededException end else RRC-->>RC: throw RoomNotAvailableException end RRC->>R: removeRole('ReservableRoom') RRC->>G: removeRole('ReservingGuest') deactivate RRC This sequence diagram demonstrates the complete reservation flow, including role attachment, validation checks, price calculations, and proper error handling. Each step ensures that business rules are followed and the system maintains consistency.

Testing with Behavior-Driven Development

While our DCI implementation provides clear separation of concerns and maintainable code, we need to ensure it works correctly through comprehensive testing. Behavior-Driven Development (BDD) with Behat is particularly well-suited for testing DCI implementations because both approaches focus on behaviors and interactions.

Understanding Behat and Gherkin

Behat is a PHP framework for BDD, which allows us to write tests in natural language using Gherkin syntax. Gherkin is a business-readable domain-specific language that lets you describe software's behavior without detailing how that behavior is implemented. This aligns perfectly with DCI's focus on separating what objects are from what they do. A typical Gherkin feature file consists of:

Feature: A description of the functionality being tested
Scenario: A specific situation being tested
Given: The initial context
When: The action being taken
Then: The expected outcome

Setting Up Behat Testing Environment

First, add the required dependencies to your composer.json:

{
    "require-dev": {
        "behat/behat": "^3.13",
        "behat/mink-extension": "^2.3",
        "behat/mink-browserkit-driver": "^2.1",
        "dmore/behat-chrome-extension": "^1.4"
    }
}

Here's how we configure Behat for our project:

# behat.yml
default:
  autoload:
    "": "%paths.base%/tests/Behat"
  suites:
    reservation:
      paths:
        features: "%paths.base%/tests/Behat/Features/Reservation"
      contexts:
        - App\Test\Behat\Context\ReservationContext
        - App\Test\Behat\Context\DatabaseContext
  extensions:
    Behat\MinkExtension:
      base_url: 'http://localhost'
      sessions:
        default:
          browser_stack: ~

Complete Behat Test Implementation

Our test implementation consists of several key components that work together to verify our DCI implementation:

Base Test Context Setup

The BaseContext class provides basic test infrastructure, handling test environment initialization and database connections. It loads the application bootstrap file and configures the test environment, including database connections and debug settings.

// tests/Behat/Context/BaseContext.php
<?php
declare(strict_types=1);

namespace App\Test\Behat\Context;

use Behat\Behat\Context\Context;
use Cake\Core\Configure;
use Cake\ORM\TableRegistry;
use Cake\TestSuite\ConnectionHelper;

abstract class BaseContext implements Context
{
    public function __construct(string $bootstrap = null)
    {
    }

    protected function initialize(): void
    {
        require_once dirname(__DIR__, 3) . '/tests/bootstrap.php';
        require_once dirname(dirname(dirname(__DIR__))) . '/config/bootstrap.php';
        ConnectionHelper::addTestAliases();
        Configure::write('debug', true);
    }

    protected function getTableLocator()
    {
        return TableRegistry::getTableLocator();
    }
}

Database Management and Fixtures

The DatabaseContext class handles database setup and cleanup, including table creation, data insertion, and deletion. It uses fixtures to populate the database with initial data, ensuring tests start with a known state. This setup allows for consistent testing conditions across different scenarios.

// tests/Behat/Context/DatabaseContext.php
<?php
declare(strict_types=1);

namespace App\Test\Behat\Context;

use Behat\Behat\Hook\Scope\BeforeScenarioScope;
use Behat\Gherkin\Node\TableNode;
use Cake\ORM\TableRegistry;

class DatabaseContext extends BaseContext
{
    private $tables = [
        'audit_logs',
        'reservation_guests',
        'reservations',
        'guests',
        'rooms',
    ];

    /**
     * @BeforeScenario
     */
    public function initializeTest(BeforeScenarioScope $scope): void
    {
        $this->initialize();
        $this->clearDatabase();
    }

    /**
     * @BeforeScenario
     */
    public function clearDatabase(): void
    {
        $connection = TableRegistry::getTableLocator()
            ->get('Reservations')
            ->getConnection();

        $connection->execute('PRAGMA foreign_keys = OFF');
        foreach ($this->tables as $tableName) {
            TableRegistry::getTableLocator()->get($tableName)->deleteAll([]);
        }
        $connection->execute('PRAGMA foreign_keys = ON');
    }

    /**
     * @Given the following rooms exist:
     */
    public function theFollowingRoomsExist(TableNode $rooms): void
    {
        $roomsTable = TableRegistry::getTableLocator()->get('Rooms');
        $headers = $rooms->getRow(0);
        foreach ($rooms->getRows() as $i => $room) {
            if ($i === 0) {
                continue;
            }
            $room = array_combine($headers, $room);
            $entity = $roomsTable->newEntity($room);
            $roomsTable->save($entity);
        }
    }

    /**
     * @Given the following guests exist:
     */
    public function theFollowingGuestsExist(TableNode $guests)
    {
        $guestsTable = TableRegistry::getTableLocator()->get('Guests');
        $headers = $guests->getRow(0);
        foreach ($guests->getRows() as $i => $guest) {
            if ($i === 0) {
                continue;
            }
            $guest = array_combine($headers, $guest);
            $entity = $guestsTable->newEntity($guest);
            $guestsTable->save($entity);
        }
    }

    /**
     * @Given the following reservations exist:
     */
    public function theFollowingReservationsExist(TableNode $reservations)
    {
        $reservationsTable = TableRegistry::getTableLocator()->get('Reservations');
        $headers = $reservations->getRow(0);
        foreach ($reservations->getRows() as $i => $reservation) {
            if ($i === 0) {
                continue;
            }
            $reservation = array_combine($headers, $reservation);
            $entity = $reservationsTable->newEntity($reservation);
            $reservationsTable->save($entity);
        }
    }
}

Reservation Testing Context

ReservationContext implements the business logic testing for our room reservation system. It manages the test workflow for reservation creation, guest management, and verification of reservation outcomes. This context translates Gherkin steps into actual system operations, handling authentication, room selection, guest assignment, and reservation confirmation. It also captures and verifies error conditions, ensuring our DCI roles and contexts behave correctly under various scenarios.

// tests/Behat/Context/ReservationContext.php
<?php
declare(strict_types=1);

namespace App\Test\Behat\Context;

use App\Context\RoomReservation\RoomReservationContext;
use App\Model\Entity\Guest;
use App\Model\Entity\Room;
use Behat\Behat\Context\Context;
use Behat\Gherkin\Node\TableNode;
use Behat\MinkExtension\Context\RawMinkContext;
use Cake\I18n\DateTime;
use Cake\ORM\TableRegistry;
use PHPUnit\Framework\Assert;

class ReservationContext extends RawMinkContext implements Context
{
    private ?Guest $authenticatedGuest = null;
    private ?Room $selectedRoom = null;
    private array $additionalGuests = [];
    private ?string $lastError = null;
    private ?float $totalPrice = null;
    private ?array $reservationDates = null;
    private ?array $lastLoggedOperation = null;

    /**
     * @Given I am authenticated as :name
     */
    public function iAmAuthenticatedAs(string $name): void
    {
        $this->authenticatedGuest = TableRegistry::getTableLocator()
            ->get('Guests')
            ->find()
            ->where(['name' => $name])
            ->firstOrFail();
    }

    /**
     * @When I try to reserve room :number for the following stay:
     */
    public function iTryToReserveRoomForTheFollowingStay(string $number, TableNode $table): void
    {
        $this->selectedRoom = TableRegistry::getTableLocator()
            ->get('Rooms')
            ->find()
            ->where(['number' => $number])
            ->contain(['Reservations'])
            ->firstOrFail();

        $this->reservationDates = $table->getRowsHash();
    }

    /**
     * @When I add :name as an additional guest
     */
    public function iAddAsAnAdditionalGuest(string $name): void
    {
        $guest = TableRegistry::getTableLocator()
            ->get('Guests')
            ->find()
            ->where(['name' => $name])
            ->firstOrFail();

        $this->additionalGuests[] = $guest;
    }

    private function executeReservation(): void
    {
        if (!$this->selectedRoom || !$this->reservationDates || !$this->authenticatedGuest) {
            return;
        }

        try {
            $context = new RoomReservationContext(
                $this->selectedRoom,
                $this->authenticatedGuest,
                $this->additionalGuests,
                new DateTime($this->reservationDates['check_in']),
                new DateTime($this->reservationDates['check_out'])
            );

            $reservation = $context->execute();
            $this->totalPrice = (float)$reservation->total_price;
            $this->lastError = null;
        } catch (\Exception $e) {
            $this->lastError = $e->getMessage();
        }
    }

    /**
     * @Then the reservation should be confirmed
     */
    public function theReservationShouldBeConfirmed(): void
    {
        $this->executeReservation();

        if ($this->lastError !== null) {
            throw new \Exception("Expected reservation to be confirmed but got error: {$this->lastError}");
        }
    }

    /**
     * @Then the total price should be :price
     */
    public function theTotalPriceShouldBe(string $price): void
    {
        $this->executeReservation();

        $expectedPrice = (float)str_replace('"', '', $price);
        if ($this->totalPrice !== $expectedPrice) {
            throw new \Exception(
                "Expected price to be {$expectedPrice} but got {$this->totalPrice}"
            );
        }
    }

    /**
     * @Then I should see an error :message
     */
    public function iShouldSeeAnError(string $message): void
    {
        $this->executeReservation();

        if ($this->lastError === null) {
            throw new \Exception("Expected error but none was thrown");
        }
        if (strpos($this->lastError, $message) === false) {
            throw new \Exception(
                "Expected error message '{$message}' but got '{$this->lastError}'"
            );
        }
    }

    /**
     * @Then the following operation should be logged:
     */
    public function theFollowingOperationShouldBeLogged(TableNode $table): void
    {
        $expectedLog = $table->getRowsHash();

        $AuditLogs = TableRegistry::getTableLocator()->get('AuditLogs');
        $lastOperation = $AuditLogs->find()->orderByDesc('created')->first();

        Assert::assertNotNull($lastOperation, 'No operation was logged');
        Assert::assertEquals($expectedLog['model'], $lastOperation->model);
        Assert::assertEquals($expectedLog['operation'], $lastOperation->operation);

        $expectedData = [];
        foreach (explode(', ', $expectedLog['data']) as $pair) {
            [$key, $value] = explode('=', $pair);
            $expectedData[$key] = $value;
        }

        Assert::assertEquals($expectedData, json_decode($lastOperation->data, true));
    }
}

And here's the Gherkin feature that describes tests for our reservation system:

# tests/Behat/Features/Reservation/room_reservation.feature
Feature: Room Reservation
    In order to stay at the hotel
    As a guest
    I need to be able to make room reservations

    Background:
        Given the following rooms exist:
            | id | number | type     | capacity | base_price | status    |
            | 1  | 101    | standard | 2        | 100.00     | available |
            | 2  | 201    | suite    | 4        | 200.00     | available |
            | 3  | 301    | deluxe   | 3        | 150.00     | available |
        And the following guests exist:
            | id | name          | email              | phone       | loyalty_level |
            | 1  | John Smith    | [email protected]   | 1234567890  | gold          |
            | 2  | Jane Doe      | [email protected]   | 0987654321  | silver        |
            | 3  | Bob Wilson    | [email protected]    | 5555555555  | bronze        |
        And the following reservations exist:
            | id | room_id | check_in    | check_out   | status    | guest_id | total_price | primary_guest_id |
            | 1  | 2       | 2025-06-01  | 2025-06-05  | confirmed | 2        | 200.00      | 2                |

    Scenario: Successfully make a room reservation
        Given I am authenticated as "John Smith"
        When I try to reserve room "101" for the following stay:
            | check_in    | 2025-07-01 |
            | check_out   | 2025-07-05 |
        And I add "Bob Wilson" as an additional guest
        Then the reservation should be confirmed
        And the total price should be "360.00"
        And the following operation should be logged:
            | model         | Reservations         |
            | operation     | reservation_created  |
            | data          | room_number=101, guest_name=John Smith, check_in=2025-07-01, check_out=2025-07-05, total_price=360, additional_guests=1 |

    Scenario: Cannot reserve an already booked room
        Given I am authenticated as "John Smith"
        When I try to reserve room "201" for the following stay:
            | check_in    | 2025-06-03 |
            | check_out   | 2025-06-07 |
        Then I should see an error "Room is not available for selected dates"

    Scenario: Cannot exceed room capacity
        Given I am authenticated as "John Smith"
        When I try to reserve room "101" for the following stay:
            | check_in    | 2025-08-01 |
            | check_out   | 2025-08-05 |
        And I add "Jane Doe" as an additional guest
        And I add "Bob Wilson" as an additional guest
        Then I should see an error "Total number of guests (3) exceeds room capacity (2)"

    Scenario: Apply loyalty discounts correctly
        Given I am authenticated as "Jane Doe"
        When I try to reserve room "301" for the following stay:
            | check_in    | 2025-09-01 |
            | check_out   | 2025-09-04 |
        Then the reservation should be confirmed
        And the total price should be "427.5"
        And the following operation should be logged:
            | model         | Reservations         |
            | operation     | reservation_created  |
            | data          | room_number=301, guest_name=Jane Doe, check_in=2025-09-01, check_out=2025-09-04, total_price=427.5, additional_guests=0 |

The test context mirrors our DCI implementation in several ways:

Role Assignment: Just as our DCI implementation attaches roles to objects, our test context manages the state of actors (guests and rooms) involved in the reservation process.
Context Creation: The test creates a RoomReservationContext with all necessary participants, similar to how our application would in production.
Behavior Verification: Tests verify both successful scenarios and error conditions, ensuring our DCI roles enforce business rules correctly.

Last two scenarios demonstrate how BDD tests can effectively verify:

Role Constraints: The ReservableRoom role's capacity constraints
Role Behaviors: The ReservingGuest role's discount calculations
Context Orchestration: The RoomReservationContext's coordination of multiple roles

The combination of DCI and BDD provides several benefits:

Clear Specifications: Gherkin scenarios serve as living documentation of system behavior
Role Verification: Each test verifies that roles implement their responsibilities correctly
Context Validation: Tests ensure that contexts properly orchestrate role interactions
Business Rule Enforcement: Scenarios verify that business rules are properly enforced through roles

Money Transfer Testing Example

Before concluding, let's look at how we tested the money transfer system from our previous article. This example demonstrates how BDD tests can effectively verify DCI pattern implementation:

Feature: Money Transfer
    In order to move money between accounts
    As an account holder
    I need to be able to transfer funds between accounts

    # Setup initial test data
    Background:
        Given the following accounts exist:
            | id | balance  | account_type | status | is_frozen |
            | 1  | 1000.00  | checking     | active | false     |
            | 2  | 500.00   | savings      | active | false     |
            | 3  | 200.00   | checking     | active | true      |
            | 4  | 300.00   | deposit_only | active | false     |

    # Tests basic transfer functionality and audit logging
    Scenario: Successful transfer between active accounts
        When I transfer "200.00" from account "1" to account "2"
        Then account "1" should have balance of "800.00"
        And account "2" should have balance of "700.00"
        # Verifies that all transfer steps are properly logged
        And an audit log should exist with:
            | foreign_key | operation       |
            | 1           | pre_withdrawal  |
            | 1           | post_withdrawal |
            | 2           | pre_deposit     |
            | 2           | post_deposit    |

    # Verifies role constraints - frozen accounts cannot perform withdrawals
    Scenario: Cannot transfer from frozen account
        When I try to transfer "100.00" from account "3" to account "2"
        Then I should get an error "Source cannot withdraw this amount"
        And account "3" should have balance of "200.00"
        And account "2" should have balance of "500.00"

    # Verifies business rule - insufficient funds
    Scenario: Cannot transfer more than available balance
        When I try to transfer "1200.00" from account "1" to account "2"
        Then I should get an error "Source cannot withdraw this amount"
        And account "1" should have balance of "1000.00"
        And account "2" should have balance of "500.00"

This feature file tests several key aspects of our DCI implementation:

Role Behavior Testing
- TransferSource role's withdrawal capabilities
- TransferDestination role's deposit functionality
- Role constraints (frozen accounts, insufficient funds)
Context Orchestration
- Proper execution of the transfer process
- Transaction atomicity (all-or-nothing transfers)
- Proper cleanup of role assignments
Business Rules Verification
- Balance constraints
- Account status restrictions
- Audit trail requirements
Error Handling
- Proper error messages for various failure scenarios
- State preservation after failed transfers
- Role constraint violations

These tests ensure that our DCI implementation maintains system integrity while enforcing business rules through role behaviors and context coordination.

Conclusion

Testing DCI implementations with Behat creates a perfect match between how we build our software and how we test it. Let's look at why this combination works so well: First, Behat's behavior-driven approach matches naturally with DCI's focus on what objects do rather than just what they are. When we write tests in Gherkin language, we describe actions and their results - just like DCI describes roles and their behaviors. This makes our tests easier to understand and write because they follow the same thinking pattern as our code. Second, both DCI and BDD focus on real-world scenarios. DCI helps us organize code around actual use cases (like making a room reservation or transferring money), while Behat lets us write tests that directly reflect these same use cases. This means our tests read like a story of what the system should do, making them valuable not just for testing but also as living documentation. Additionally, the way Behat structures tests with "Given-When-Then" steps fits perfectly with how DCI contexts work:

"Given" steps set up our data objects
"When" steps trigger the context's actions
"Then" steps verify that roles performed their behaviors correctly

This natural alignment between DCI and BDD testing makes our development process more straightforward and our tests more reliable. We can be confident that our tests are checking the right things because they're structured in the same way as the system they're testing.

Demo Project for Article

The complete example, including all tests and implementations, is available at: https://github.com/skie/cakephp-dci. This article is part of the CakeDC Advent Calendar 2024 (December 19th 2024)

Written by Yevgeny on December 19, 2024

CakeDC Blog

Streaming database results

Written by Jorge on December 17, 2024 • 150 VIEWS

Latest articles

CakeDC Search Filter Plugin

Setup

Filters

Criteria Purpose and Usage

Filters Usage

Controller Setup

Implementing Search Filters

Table Configuration

View Implementation

JavaScript Integration

Frontend Vue App Widgets

Custom Filters and Custom Widgets

Custom Filter Class

Custom Criterion Implementation

Controller Integration

Custom Vue.js Widget

Component Registration

Demo Project for Article

Conclusion

5 CakePHP security tips

Testing DCI with Behavior-Driven Development

Room Reservation System Overview

Database Structure

Testing with Behavior-Driven Development

Understanding Behat and Gherkin

Setting Up Behat Testing Environment

Complete Behat Test Implementation

Base Test Context Setup

Database Management and Fixtures

Reservation Testing Context

Money Transfer Testing Example

Conclusion

Demo Project for Article

Written by Jorge on December 17, 2024 •
150 VIEWS