CakeDC Blog

TIPS, INSIGHTS AND THE LATEST FROM THE EXPERTS BEHIND CAKEPHP

Ed Finkler - Founder, Open Sourcing Mental Illness

Written by Megan on May 18, 2017 •
7343 VIEWS

Do you know who Ed Finkler is or what OSMI does? If you are in the developer community, then it definitely is a name you should get to know.

Open Sourcing Mental Illness is a non-profit organization dedicated to raising awareness, educating, and providing resources to support mental wellness in the tech and open source communities.

CakeDC and CakePHP has long supported and stood behind OSMI - Ed Finkler has been instrumental in making mental health a topic of discussion, and opening up lines of support for mental wellness in tech. Mental health and wellness are close to our hearts and we want to share with you OSMI and why you should support it.

Ed has been active in bringing forward a previously rarely discussed topic - mental health. Being an advocate of mental health awareness and using his own experiences as a developer, he has recently announced that he is now able to go full time into OSMI. This is really fantastic news and CakeDC stands 100% behind him. We caught us with him to find out more.

We love that you are now putting all your time into OSMI - but what was the Catalyst for your decision to focus full time into OSMI?
What we found is that we simply had to much to do, and not enough time to do it. Everyone at OSMI are volunteers, and it was becoming increasingly challenging to find the bandwidth for anyone to complete major tasks. We are ambitious, and our ambition far exceeded the time available. I couldn’t ask it of anyone else, but I could make a decision myself -- that I would step away from my CTO role at a tech startup and dedicate myself to OSMI full-time.
What is your favorite thing to do out of ‘office’ hours (Hobbies/activities etc)?
Generally I find myself watching movies or good TV shows, or playing video games (I’m deep in Mass Effect: Andromeda right now). I also write electronic music, which you can hear at deadagent.net.
Do you think that companies are becoming more receptive to your message and becoming more open about speaking about mental health?
Yes, I think so. Companies in general are gradually becoming more aware of the need to discuss mental health openly, the same way we discuss other serious public health issues, like cancer and heart disease. But there’s a long, long way to go, and we are just taking our first steps as an industry to deal with this in a healthy way.
Have you seen a marked difference in people opening up about their personal experiences?
I definitely have observed, over and over, that when someone takes that first step forward, others follow. Fear is the thing that keeps mental illness hidden, and fear is why so many suffer in silence. Seeing someone speak without fear about their own issues empowers the listener. They may not need to stand up on stage like I do, but I’ve had numerous people tell me that hearing someone speak openly was what allowed them to seek help and/or start speaking openly about the subject.
What would you say is the biggest misconception that you have encountered when speaking about and sharing your personal experiences?
I think the biggest misconception I encounter is companies believing that by simply offering some level of mental health care in medical coverage, they’ve done all they can. That would be fine if we treated mental disorders like we do cancer or heart disease or diabetes, but we don’t -- we are afraid to discuss it, and as a consequence, we don’t know what to look for, why it matters, and how to seek help. In the absence of consistent, positive affirmation that it’s a safe topic, our default is to be afraid to discuss it. That keeps people from seeking the help they need.
Biggest piece of advice that you would give someone battling with mental health issues
You are not alone. Lots of people are like you. There is no shame in what you deal with. You are stronger than you know.
You recently spoke about mental health breaks on the OSMI blog, how would someone know they are in need of one and how would you suggest for employees to bring this topic up with their employers?
I am leery of giving specific health advice, but in general I’d say this: listen to your mind and your body, and remember that your own health is far, far more important than any job. Plus, if you’re healthy, you’ll be able to do your job much better.
In the last 5 years, you have achieved incredible breakthroughs and achievements in bringing this to the fore - where do you see OSMI and mental illness awareness in the next 5 years?
Ultimately, those two things are intertwined. OSMI will continue to grow because so many of us suffer from this, and more and more of us are realizing that we aren’t alone. That we aren’t broken. That we aren’t without hope. OSMI is about giving hope to those that felt they had none. Giving compassion to those who are hardest on themselves.
It’s my sincere hope that OSMI will drive the awareness of mental health in the tech workplace and change what we choose to value in employers and employees. However we get there, I believe we will succeed.
As someone suffering and wanting to find out more or be involved, how do we reach out, what should we expect and where should we go?
There are lots of ways to help OSMI, and all you really need is a willingness to spend some of your time working with us. You should visit https://osmihelp.org and learn more about our work, and then email [email protected] to talk to us about volunteering.
As a business with employees in the tech industry, what should we do to make mental health more accessible
For each employer there’s a different answer, but there are some general things to keep in mind. The biggest one is that the well-being of your employees must be a top priority. It’s an easy thing to say, but if you truly value it, you’ll avoid doing what so many organizations do: rewarding overwork and unhealthy “loyalty.” Ping pong tables and bean bag chairs don’t make people healthier, and neither do free snacks and beer at the office. They’re short-term tricks to get people to come to you and maybe stay in the office longer, but they don’t encourage a healthy work/life balance. Too many developers think their work IS their life. That’s a mistake.
Long term, what works are reasonable work hours, easy access to mental and physical health care, and promoting healthy preventative habits. Employees who feel that their well-being is demonstrably valued will be more productive and stay with your organization longer.
I also strongly encourage everyone in a leadership position to take Mental Health First Aid <https://www.mentalhealthfirstaid.org>, a program that teaches the skills to respond to the signs of mental illness and substance use.
Quote to live by or key advice to follow every day
One time I was encouraged to do a six-word memoir, and this is what I came up with:
“By helping others, I save myself.”

Thanks to Ed! We absolutely loved catching up with him about OSMI, we hope that you take a moment to check out the links and find out more to get involved and continue this important conversation!

For more information, be sure to check out https://osmihelp.org/about/about-osmi

Latest articles

56 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

73 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

117 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

Ed Finkler - Founder, Open Sourcing Mental Illness

Written by Megan on May 18, 2017 • 7343 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 Megan on May 18, 2017 •
7343 VIEWS