If you own a motorhome with a Truma Combi heater, you’ve probably shared my frustration: You’d like to turn on your boiler 20 minutes before you come back to the van, so you can take a shower immediately, but the standard CPPlus controller doesn’t allow internet connectivity out of the box. Sure, you can buy an iNet Box, but it requires a yearly subscription and—here is the catch—your CPPlus unit must be “iNet Ready.” Mine wasn’t.

Instead of paying for a subscription and upgrading my hardware to a closed ecosystem, I decided to build my own solution. Inspired by the olivluca/truminus and olivluca/TrumaDisplay projects, my original plan was to build an iNet Box simulator that would sit in parallel on the Truma TIN bus. Even though my CPPlus didn’t say “iNet Ready,” it was a brand-new 2025 heater, so I gambled on it being compatible. Spoiler alert: I was wrong.

I’ve developed the core of the project using Claude Code and Kimi K2.6. It’s been an incredible experience acting as the orchestrator, focusing on the UX and QA, while letting the AI handle the heavy lifting of implementation details.

Phase 1: The “iNet” Gamble

My first approach was conservative. I didn’t want to remove the original CPPlus, so I planned to build a “Man-in-the-Middle” device. Using an ESP32 C3 Supermini, I tried to emulate an iNet Box to sit alongside the original controller on the TIN-Bus.

I had high hopes. My heater was a brand-new 2025 model, and I assumed Truma would have made it compatible by default. I spent time trial-and-error-coding the emulation layer, but the heater simply wouldn’t recognize the device. The lesson? If the screen doesn’t say “iNet Ready,” it really isn’t.

The first prototype with the ESP32 C3 and wires everywhere

Phase 2: Pivoting to the CYD (Cheap Yellow Display)

Since I couldn’t “talk” to the CPPlus, I decided to replace the CPPlus. I moved the project to the ESP32-2432S028, popularly known as the CYD (Cheap Yellow Display). This gave me a 2.8-inch touchscreen and some GPIOs.

To make it fit the motorhome’s aesthetic, I designed a custom PCB the exact same size as the screen. This “sandwich” design meant the unit would be deep but have a small footprint on the wall, making it much easier to mount.

The Software Grind: I spent hours at my desk iterating on the UI (AI doesn’t hit the bullseye with C++ and embedded hardware as quick as with other more common technologies like PHP, Javascript… etc.

I wanted a professional feel, with intuitive menus and a built-in web server. The biggest headache was the ESP32’s memory. Between the graphic library (LVGL/TFT_eSPI), the Wi-Fi stack, and the web server, I kept hitting “Out of Memory” crashes. It took many some nights of code optimization and AI-assisted debugging to get the loop running smoothly.

The CYD display showing the main menu

Phase 3: Field Testing & Reverse Engineering

Once the UI was stable, it was time to move from the desk to the van. This is where things got real. I used WomoLIN logs as a baseline, but since my heater was so new, the commands didn’t match perfectly, so I had to perform Live Sniffing. I connected the CYD in parallel with the original Truma panel and watched the hex codes fly by.

Working inside the van, wires connected to the Truma unit

The “Cold Sweat” Moment: During one of these tests, the heater suddenly locked up. A red light started flashing: Error E545. I searched every manual—nothing. The heater was unresponsive. I had to literally dismantle the furniture to reach the Combi unit’s core. After a few tense minutes of panic, I found the physical reset button. A long press later, the “clac-clac” of the diesel pump returned. I’ve never been so happy to hear a clicking noise in my life.

The Truma unit

Phase 4: Adding the “Pro” Features (Victron & Ultimatron)

Since I had a powerful screen, I figured: why stop at the heater? I wanted a “Command Center.”

1. Victron SmartSolar MPPT: I connected to it via bluetooth based on chrisj7903/Read-Victron-advertised-data project. I had to fix some decryption issues because my newer MPPT used a slightly different frame format than the open-source libraries I found.
2. Ultimatron LiFePo4: I integrated the battery status via Bluetooth/Serial based on the sergkh/node-ultimatron-battery project.

Now, in one single glance, I could see my room temperature, manage my heater and boiler, and check my solar harvest and my battery percentage.

Screen showing the Solar and Battery stats

I also dedicated significant time to fine-tuning the web server to mirror the physical display’s state. By implementing a real-time WebSocket (WS) connection, I ensured that any change on the web interface is instantly reflected on the screen and vice versa, creating a seamless, zero-latency synchronization

Landscape view of the web app

Portrait view of the web app

Phase 5: 3D Case Design & Installation

The final hurdle was physical. In my van, the auxiliary drop-down bed partially covers the original control area. I had to mount the new panel as low as possible so I could still see the temperature while lying in bed.

I used Shapr3D to design a bespoke enclosure. I wanted it to look factory-spec, so I added a recessed Truma logo. A friend printed it for me on a multi-color Bambu Lab printer, and the result was incredible. To hide the old screw holes in the wood, I used a matching wood-effect vinyl—the integration is seamless.

Wood Machining & Panel Adaptation

The physical integration was a delicate part of the project. In my motorhome, the auxiliary drop-down bed partially blocks the original control area when lowered. I had to study the dimensions carefully to reposition the new system as low as possible without losing visibility or functionality.

After taking precision measurements, I proceeded to machine the original wooden panel. This required immense patience; it was crucial not to splinter the plywood while creating the exact cutouts for the CYD screen and the internal electronics. Ensuring everything was aligned and firm, while taking advantage of the empty space behind the panel, was a major milestone

Conclusion

Developing this controller was a significant technical challenge. Reversing the proprietary TIN-bus protocol and resolving critical errors, such as the E545, required nerves of steel and extensive debugging.

The result is a system that outperforms the original hardware in responsiveness and telemetry. It now offers global remote access and a data granularity that exceeds the official iNet Box’s capabilities. Future iterations may include water level monitoring, but the current focus is the system’s deployment in a live environment.

The post Advanced Motorhome Truma Control Panel: A Custom ESP32 CYD Journey appeared first on Víctor Dorado.

Large Language Models (LLMs) have proven remarkably effective at handling general-purpose queries, but they struggle when precision, domain-specificity, or continuously evolving knowledge are required. Out-of-the-box, their responses are often too shallow or prone to hallucination, which makes them unsuitable for production-grade information retrieval tasks.

Retrieval-Augmented Generation (RAG) was introduced as a solution to this limitation, bridging LLMs with external knowledge bases. Yet, most “naive” RAG implementations remain constrained: they typically rely on basic vector similarity search and flat document retrieval, lacking deeper semantic reasoning, graph-based relationships, or robust orchestration capabilities. As a result, these pipelines often fail to deliver the context-rich, reliable answers demanded by real-world applications in domains such as legal or healthcare.

This is where LightRAG comes into play. LightRAG enriches retrieval by leveraging structured knowledge representations and semantic graphs, enabling more accurate and context-aware responses.

However, LightRAG is a single-query tool, and does not support chat history or other components within workflows. N8N, in turn, provides a powerful workflow automation layer, making it possible to seamlessly integrate enhanced RAG pipelines into operational systems and complex data flows. This is achieved through AI agents, which can leverage LightRAG alongside other tools to deliver more tailored responses and actions.

In this post, I’ll walk through my experience combining LightRAG with N8N to move beyond naive RAG and build a more robust, production-ready approach to information retrieval.

How LightRAG works

First, a RAG system must process documents. Instead of retrieving isolated text chunks from them, like standard RAG solutions, LightRAG also constructs a knowledge graph where entities, concepts, and their relationships are explicitly represented. This allows the system to capture semantic connections that naive RAG pipelines typically miss.

At retrieval time, when a query is received, it pulls the most similar passages like standard RAG solutions do, but LightRAG also performs a graph-based retrieval process to identify the most relevant nodes and relationships.

Finally, the retrieved graph substructure and the most relevant text chunks are fed into the LLM, which can leverage both the textual evidence and the relational context. The result is a response that is not only grounded in the source documents but also informed by semantic structure and contextual relevance, enabling higher-quality answers for complex, domain-specific use cases.

We will set up our workbench with Docker Compose, a tool for defining and running multi-container applications. Docker Compose uses a a docker-compose.yml file that specifies all the configuration required by the containers.

First, we define the PostgreSQL service—a database server with basic vector storage capabilities. The Docker Hub image shangor/postgres-for-rag is well-suited to our needs, as it comes with both the pgvector and Apache AGE extensions preinstalled. This image uses fixed defaults rag/rag/rag for the database name, user, and password, and cannot be configured via environment variables.

services:
  postgres:
    container_name: postgres
    image: shangor/postgres-for-rag:v1.0
    container_name: postgres
    volumes:
      - postgres_data:/var/lib/postgresql/16/main
    ports:
      - "5432:5432"
    environment: {}
    restart: unless-stopped
volumes:
  postgres_data:

services:
  postgres:
    container_name: postgres
    image: shangor/postgres-for-rag:v1.0
    container_name: postgres
    volumes:
      - postgres_data:/var/lib/postgresql/16/main
    ports:
      - "5432:5432"
    environment: {}
    restart: unless-stopped
volumes:
  postgres_data:

Then, we add the LightRAG service:

services:
  postgres:
   ...
  lightrag:
    container_name: lightrag
    image: ghcr.io/hkuds/lightrag:latest
    ports:
      - "9621:9621"
    volumes:
      - lightrag_data:/app/data
    env_file:
      - .lightrag-env
    restart: unless-stopped
volumes:
  postgres_data:
  lightrag_data:

services:
  postgres:
   ...
  lightrag:
    container_name: lightrag
    image: ghcr.io/hkuds/lightrag:latest
    ports:
      - "9621:9621"
    volumes:
      - lightrag_data:/app/data
    env_file:
      - .lightrag-env
    restart: unless-stopped
volumes:
  postgres_data:
  lightrag_data:

We will keep all the configuration in a separate .lightrag-env file. Since it is quite large, placing it directly in the docker-compose.yml would bloat the file. There are many environment variables available, but here I will only show the ones I have configured.

### Reranker Configuration
RERANK_BINDING=cohere
RERANK_MODEL=rerank-v3.5
RERANK_BINDING_HOST=https://api.cohere.com/v2/rerank
RERANK_BINDING_API_KEY=YOUR_API_KEY

### LLM Configuration
LLM_BINDING=openai
LLM_MODEL=gpt-4.1-mini
LLM_BINDING_HOST=https://api.openai.com/v1
LLM_BINDING_API_KEY=YOUR_API_KEY

### Embedding Configuration
EMBEDDING_BINDING=openai
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_DIM=1536
EMBEDDING_BINDING_HOST=https://api.openai.com/v1
EMBEDDING_BINDING_API_KEY=YOUR_API_KEY

### Storage Configuration
LIGHTRAG_KV_STORAGE=PGKVStorage
LIGHTRAG_DOC_STATUS_STORAGE=PGDocStatusStorage
LIGHTRAG_GRAPH_STORAGE=PGGraphStorage
LIGHTRAG_VECTOR_STORAGE=PGVectorStorage

### PostgreSQL Configuration
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_USER=rag
POSTGRES_PASSWORD=rag
POSTGRES_DATABASE=rag
POSTGRES_MAX_CONNECTIONS=12

### Reranker Configuration
RERANK_BINDING=cohere
RERANK_MODEL=rerank-v3.5
RERANK_BINDING_HOST=https://api.cohere.com/v2/rerank
RERANK_BINDING_API_KEY=YOUR_API_KEY

### LLM Configuration
LLM_BINDING=openai
LLM_MODEL=gpt-4.1-mini
LLM_BINDING_HOST=https://api.openai.com/v1
LLM_BINDING_API_KEY=YOUR_API_KEY

### Embedding Configuration
EMBEDDING_BINDING=openai
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_DIM=1536
EMBEDDING_BINDING_HOST=https://api.openai.com/v1
EMBEDDING_BINDING_API_KEY=YOUR_API_KEY

### Storage Configuration
LIGHTRAG_KV_STORAGE=PGKVStorage
LIGHTRAG_DOC_STATUS_STORAGE=PGDocStatusStorage
LIGHTRAG_GRAPH_STORAGE=PGGraphStorage
LIGHTRAG_VECTOR_STORAGE=PGVectorStorage

### PostgreSQL Configuration
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_USER=rag
POSTGRES_PASSWORD=rag
POSTGRES_DATABASE=rag
POSTGRES_MAX_CONNECTIONS=12

For testing purposes, I’ve used OpenAI, which is inexpensive and easy to set up. If you have access to a capable GPU, you can also run an Ollama service as an alternative.

Using a reranker is crucial, as it greatly enhances the quality of responses provided by LightRAG. In my case, I chose Cohere, which offers a simple free plan, perfectly sufficient for our testing needs.

Finally, we must add the N8N service. With N8N, we will implement the AI agent that leverages LightRAG as one of its tools.

services:
  postgres:
   ...
  lightrag:
   ...
  n8n:
    image: n8nio/n8n:latest
    ports:
      - "5678:5678"
    env_file:
      - .n8n-env
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on:
      - postgres
    restart: unless-stopped
volumes:
  postgres_data:
  lightrag_data:
  n8n_data:

services:
  postgres:
   ...
  lightrag:
   ...
  n8n:
    image: n8nio/n8n:latest
    ports:
      - "5678:5678"
    env_file:
      - .n8n-env
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on:
      - postgres
    restart: unless-stopped
volumes:
  postgres_data:
  lightrag_data:
  n8n_data:

DB_TYPE=postgresdb
DB_POSTGRESDB_HOST=postgres
DB_POSTGRESDB_PORT=5432
DB_POSTGRESDB_DATABASE=rag
DB_POSTGRESDB_USER=rag
DB_POSTGRESDB_PASSWORD=rag

N8N_HOST=http://localhost
N8N_PORT=5678
N8N_PROTOCOL=http
N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true

DB_TYPE=postgresdb
DB_POSTGRESDB_HOST=postgres
DB_POSTGRESDB_PORT=5432
DB_POSTGRESDB_DATABASE=rag
DB_POSTGRESDB_USER=rag
DB_POSTGRESDB_PASSWORD=rag

N8N_HOST=http://localhost
N8N_PORT=5678
N8N_PROTOCOL=http
N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true

Now we can run docker compose up to deploy our stack. We will have LightRAG available at http://localhost:9621

In the screen above, I’ve already uploaded a document of my city’s mobility regulation. It covers cycle lanes, pedestrian areas, traffic, and how they interact within the urban environment. After waiting for the processing to be done (~15 minutes for a 130 page document), we can check out the knowledge graph and even make queries.

We obtained a fairly good response, along with the references used by the algorithm:

• [KG] – References in the Knowledge Graph: either single entities or relations between two entities.
• [DG] – Text chunks retrieved from a document.

We can also play with different parameters: Query mode (global, local, hybrid… etc.), response format, KG Top K, Chunk Top K, whether to enable or not reranking… refer to the LightRAG documentation for more info on these topics.

Introducing N8N

LightRAG can handle simple queries, but it lacks chat history, a system prompt (although it seems to have a “User Prompt” setting, it didn’t work for me), and other tools needed to properly manage a complete automation pipeline.

With N8N, we can implement the ideal orchestration mechanisms to fully unleash LightRAG’s search capabilities. We will set up a basic AI agent that includes a “LightRAG Tool”, which it can use to perform searches while generating more thoughtful responses that are also aligned with a custom system prompt.

Installing the LightRAG Tool

There is not an official node for interacting with LightRAG. Fortunately, there is a contributed one: n8n-nodes-lightrag, that will allow us connecting an AI agent with our LightRAG instance.

Go to settings, in the bottom left corner, under the three points button:

In the next screen, go to “Community Nodes” and install it:

Creating our AI Agent

Now it’s finally time to create our AI Agent. We will use an OpenAI Model with gpt-4.1-mini configured, a simple memory node, and our LightRAG Tool

For our system prompt, we will use simple instructions:

You are an information assistant on Urban Mobility in Logroño, designed to answer user questions based on municipal regulations.

Retrieve relevant information and provide a concise, precise, and informative response to the user’s question. To do so, always use the "Light Rag Query" tool to fetch information from the company’s corpus, which is hosted on a LightRAG server. You should ask the tool any questions you deem necessary, including multiple queries if needed.

This tool will always return an answer along with the references used, for example:

------------------------------
Question:
Tell me in which cases wearing a helmet is required.

Answer:
Wearing a helmet is mandatory in several cases according to the regulations… etc.
References
[KG] certified helmet
[KG] certified helmet – motorcycles
[DC] MOBILITY-ORDINANCE-2019.pdf
------------------------------

A [KG] reference means it was obtained from the Knowledge Graph and can be either:

 - [KG] entity: A single entity
 - [KG] entity1 – entity2: A relationship between entity1 and entity2

A [DC] reference means it was obtained from text chunks in documents:

 - [DC] document name

However, you should not provide the references used unless explicitly asked for them.

If the answer cannot be found using the "Light Rag Query" tool, respond with:
"I cannot find the answer in the available resources."

You are an information assistant on Urban Mobility in Logroño, designed to answer user questions based on municipal regulations.

Retrieve relevant information and provide a concise, precise, and informative response to the user’s question. To do so, always use the "Light Rag Query" tool to fetch information from the company’s corpus, which is hosted on a LightRAG server. You should ask the tool any questions you deem necessary, including multiple queries if needed.

This tool will always return an answer along with the references used, for example:

------------------------------
Question:
Tell me in which cases wearing a helmet is required.

Answer:
Wearing a helmet is mandatory in several cases according to the regulations… etc.
References
[KG] certified helmet
[KG] certified helmet – motorcycles
[DC] MOBILITY-ORDINANCE-2019.pdf
------------------------------

A [KG] reference means it was obtained from the Knowledge Graph and can be either:

 - [KG] entity: A single entity
 - [KG] entity1 – entity2: A relationship between entity1 and entity2

A [DC] reference means it was obtained from text chunks in documents:

 - [DC] document name

However, you should not provide the references used unless explicitly asked for them.

If the answer cannot be found using the "Light Rag Query" tool, respond with:
"I cannot find the answer in the available resources."

We must also configure the LightRAG Tool. First, configure the URL where N8N can access the lightRAG server. As we have a Docker internal network, every container is seen by the others by its name, in our case “lightrag”.

Then, configure the query to be provided by the model, the “mix” strategy and enable reranking:

You can try out the different modes to observe their differences. For more details, refer to the LightRAG documentation.

Evaluating our agent

Finally, we can open a chat session with our agent and ask any question. For example:

Our AI Agent will start processing the request:

We inmediately receive a response, and we can check out the execution process, as it is logged.

This is the query that our agent sent to LightRAG, and its response:

We can see that the response is quite similar to the one provided by LightRAG, but this was a relatively simple question. We could instruct our agent to query LightRAG more effectively, respond in a more informal tone, consult other information sources, or even perform actions.

Let’s try a more complicated question:

We can observe how the agent synthesizes the information. It adds another layer of abstraction, allowing it to emphasize certain aspects of the information provided by LightRAG.

However, this example still doesn’t add much beyond simple LightRAG queries. But keep in mind that, with N8N, the possibilities are vast: for instance, we could equip the agent with a weather tool that checks today’s conditions and advises the user on any precautions they should take.

LightRAG represents a significant advancement in the field of Retrieval-Augmented Generation. It outperforms traditional or “naive” RAG solutions by combining efficient knowledge retrieval with contextual reasoning, all while maintaining a moderate token cost. This makes it a powerful tool for building intelligent, scalable, and cost-effective information systems.

The post Supercharging RAG Information Retrieval with N8N and LightRAG appeared first on Víctor Dorado.

The post Tests de Kernel en Drupal: cuando los tests unitarios no son suficiente appeared first on Víctor Dorado.

Además, podremos ver un caso típico de testing por intervalos, donde debemos comprobar que cada intervalo produce la salida correcta.

The post Tests Unitarios en Drupal. Parte 2: Sujetos de test con dependencias appeared first on Víctor Dorado.

En este vídeo veremos, de forma muy resumida, cómo se puede crear un test unitario en Drupal. Crearemos un servicio muy simple y un test que compruebe que el servicio se comporta como esperamos. Además, podremos apreciar, en primera persona, las ventajas de programar con TDD (Test Driven Development).

The post Tests unitarios en Drupal con PHPUnit y PHPStorm appeared first on Víctor Dorado.

“Develop and test your AWS applications locally to reduce development time and increase product velocity. Reduce unnecessary AWS spend and remove the complexity and risk of maintaining AWS dev accounts.”

LocalStack™ offers both a community and a pro version, allowing users to access the community version for free. In this guide, we’ll walk you through configuring a local instance of Simple Storage Service (S3) hosted in a DDEV container.

Installing Drupal with DDEV

From the DDEV quickstart guide, we can follow these steps to set up a new Drupal 11 project:

mkdir my-drupal11-site && cd my-drupal11-site \
ddev config --project-type=drupal11 --docroot=web \
ddev composer create drupal/recommended-project:^11.0.0 \
ddev composer require drush/drush \
ddev drush site:install --account-name=admin --account-pass=admin -y \
ddev launch

mkdir my-drupal11-site && cd my-drupal11-site \
ddev config --project-type=drupal11 --docroot=web \
ddev composer create drupal/recommended-project:^11.0.0 \
ddev composer require drush/drush \
ddev drush site:install --account-name=admin --account-pass=admin -y \
ddev launch

Important:

At the time of writing this guide, the S3 Filesystem module requires drupal/core:^11.0.0. This means it is not compatible with Drupal 11.1, which is currently the latest core version. To address this, we’ve specified the ^11.0.0 version constraint in Composer, ensuring the installation of the latest 11.0.x version.

With these steps, you should now have a DDEV project running a clean Drupal installation with Drush.

Adding the LocalStack service to DDEV

Next, we need to create a file named docker-compose.localstack.yml in the root of the .ddev directory with the following content:

services:
  localstack:
    container_name: ddev-${DDEV_SITENAME}-localstack
    image: localstack/localstack
    restart: always
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
      com.ddev.approot: $DDEV_APPROOT
    environment:
      # LocalStack config: https://docs.localstack.cloud/references/configuration/
      - VIRTUAL_HOST=$DDEV_HOSTNAME
      - DEBUG=0
    ports:
      - 4566:4566
    volumes:
      - "./localstack/volume:/var/lib/localstack"
      - "/var/run/docker.sock:/var/run/docker.sock"

  web:
    links:
      - localstack

services:
  localstack:
    container_name: ddev-${DDEV_SITENAME}-localstack
    image: localstack/localstack
    restart: always
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
      com.ddev.approot: $DDEV_APPROOT
    environment:
      # LocalStack config: https://docs.localstack.cloud/references/configuration/
      - VIRTUAL_HOST=$DDEV_HOSTNAME
      - DEBUG=0
    ports:
      - 4566:4566
    volumes:
      - "./localstack/volume:/var/lib/localstack"
      - "/var/run/docker.sock:/var/run/docker.sock"

  web:
    links:
      - localstack

(based on https://docs.localstack.cloud/getting-started/installation/#docker-compose)

Then, we must restart the DDEV project:

ddev restart

ddev restart

And we will be able to open a ssh connection to our new localstack container:

docker exec -ti ddev-drupal11-localstack-localstack bash

docker exec -ti ddev-drupal11-localstack-localstack bash

Following the instructions from the LocalStack S3 User Guide, we will now proceed to create a bucket:

awslocal s3api create-bucket --bucket sample-bucket

awslocal s3api create-bucket --bucket sample-bucket

And we will get a positive feedback response:

{
    "Location": "/sample-bucket"
}

{
    "Location": "/sample-bucket"
}

At this point, we now have a local AWS S3 instance up and running inside a container, accessible as localstack from the other DDEV project containers.

Important Caveat:

The community version of the LocalStack container does not include persistence. This feature is only available in the paid LocalStack Pro version. As a result, when using the community edition, all buckets and their content will be lost each time the localstack container is restarted. This limitation means we can only perform very basic tests with this setup.

Configuring EC2 Metadata Mock

Many AWS SDKs rely on a critical component available in every EC2 instance: a metadata server accessible at 169.254.169.254. Since this server won’t be available from our DDEV web container, we need to mock it using a tool provided by Amazon.

Amazon EC2 Metadata Mock

Fortunately, this tool is available as a Docker image, which allows us to create another container within our DDEV project to host it. To set this up, create a file named docker-compose.ec2-metadata-mock.yml inside the .ddev directory with the following content:

services:
  ec2-metadata-mock:
    container_name: ddev-${DDEV_SITENAME}-ec2-metadata-mock
    image: public.ecr.aws/aws-ec2/amazon-ec2-metadata-mock:v1.12.0
    restart: always
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
      com.ddev.approot: $DDEV_APPROOT
    environment: []
    ports:
      - 1338:1338
    volumes: []

  web:
    links:
      - ec2-metadata-mock

services:
  ec2-metadata-mock:
    container_name: ddev-${DDEV_SITENAME}-ec2-metadata-mock
    image: public.ecr.aws/aws-ec2/amazon-ec2-metadata-mock:v1.12.0
    restart: always
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
      com.ddev.approot: $DDEV_APPROOT
    environment: []
    ports:
      - 1338:1338
    volumes: []

  web:
    links:
      - ec2-metadata-mock

The tool listens on port 1338 instead of the standard port 80, but we’ll address this difference later. More details will follow in the next sections.

Restart DDEV to deploy the new container:

ddev restart

ddev restart

After restarting, the EC2 Metadata Mock will be running on port 1338 and accessible as ec2-metadata-mock from other containers within the DDEV project.

We now can make a simple request from our web container to http://ec2-metadata-mock:1338/

ddev ssh

curl http://ec2-metadata-mock:1338/latest/meta-data/iam/security-credentials
baskinc-role

curl http://ec2-metadata-mock:1338/latest/meta-data/iam/security-credentials/baskinc-role
{
  "Code": "Success",
  "LastUpdated": "2020-04-02T18:50:40Z",
  "Type": "AWS-HMAC",
  "AccessKeyId": "12345678901",
  "SecretAccessKey": "v/12345678901",
  "Token": "TEST92test48TEST+y6RpoTEST92test48TEST/8oWVAiBqTEsT5Ky7ty2tEStxC1T==",
  "Expiration": "2020-04-02T00:49:51Z"
}

ddev ssh

curl http://ec2-metadata-mock:1338/latest/meta-data/iam/security-credentials
baskinc-role

curl http://ec2-metadata-mock:1338/latest/meta-data/iam/security-credentials/baskinc-role
{
  "Code": "Success",
  "LastUpdated": "2020-04-02T18:50:40Z",
  "Type": "AWS-HMAC",
  "AccessKeyId": "12345678901",
  "SecretAccessKey": "v/12345678901",
  "Token": "TEST92test48TEST+y6RpoTEST92test48TEST/8oWVAiBqTEsT5Ky7ty2tEStxC1T==",
  "Expiration": "2020-04-02T00:49:51Z"
}

The Expiration value will trigger a warning later when validating the configuration in Drupal. However, this warning can safely be ignored.

For more information on making requests to the EC2 Metadata Mock, refer to the official documentation at https://github.com/aws/amazon-ec2-metadata-mock/tree/main?tab=readme-ov-file#making-a-request.

Patch the aws-sdk-php Composer package

The simplest way to make the AWS SDK recognize a custom EC2 Metadata Service location is by directly modifying its hardcoded IP address:

Change the value of the class constant Aws\Credentials\InstanceProfileProvider::DEFAULT_METADATA_SERVICE_IPv4_ENDPOINT to http://ec2-metadata-mock:1338

<?php
namespace Aws\Credentials;

use ...

/**
 * Credential provider that provides credentials from the EC2 metadata service.
 */
class InstanceProfileProvider
{
    ...
    const DEFAULT_METADATA_SERVICE_IPv4_ENDPOINT = 'http://ec2-metadata-mock:1338';

<?php
namespace Aws\Credentials;

use ...

/**
 * Credential provider that provides credentials from the EC2 metadata service.
 */
class InstanceProfileProvider
{
    ...
    const DEFAULT_METADATA_SERVICE_IPv4_ENDPOINT = 'http://ec2-metadata-mock:1338';

This way, the credentials provider accessed will be our EC2 Metadata Mock server.

You can make a composer patch to retain this configuration. See https://github.com/cweagans/composer-patches for more information.

Edit /etc/hosts file in the host computer

From the web container, the LocalStack container is accessible as localstack via http://localstack:4566. This setup enables internal communication between Drupal and LocalStack to function seamlessly.

However, we also need access to the bucket from the host computer (our PC), as the web browser navigating the Drupal site will be running locally and needs to access the files stored in the bucket.

So, add a new hostname to your localhost definition line inside your /etc/hosts file:

127.0.0.1 localhost localstack
127.0.1.1 MY-PC

# The following lines are desirable for IPv6 capable hosts
::1 ip6-localhost ip6-loopback
fe00::0 ip6-localnet
ff00::0 ip6-mcastprefix
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters

127.0.0.1 localhost localstack
127.0.1.1 MY-PC

# The following lines are desirable for IPv6 capable hosts
::1 ip6-localhost ip6-loopback
fe00::0 ip6-localnet
ff00::0 ip6-mcastprefix
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters

And that’s it! Both your web browser and the DDEV web container can now access the bucket via http://localstack:4566/sample-bucket.

Remember, we selected the “Use path-style endpoint” option in the S3 FileSystem configuration, which ensures compatibility with this setup.

Configuring Drupal

Install the module “S3 Filesystem”.

ddev composer require drupal/s3fs \
ddev drush en s3fs

ddev composer require drupal/s3fs \
ddev drush en s3fs

And go to configure its settings at /admin/config/media/s3fs.

We will only have to fill these settings:

• S3 Bucket Name: sample-bucket
• Use a Custom Host: Checked
• Hostname: http://localstack:4566
• Use path-style endpoint: Checked

Now, you can go to the “Actions” tab or visit /admin/config/media/s3fs/actions and click on the “Validate configuration” button.

Despite the warning about the EC2 Metadata Mock credentials’ expiration date (set to the year 2020), the settings will still be validated correctly. This means that your Drupal configuration will function as expected, even with this warning present.

Make an image field use the new S3 storage

Go to /admin/structure/types/manage/article/fields/node.article.field_image so we can configure the image field in the default “Article” content type:

Then, change the Field Storage to “S3 File System” and click on “Save settings”.

From now on, any new images added to articles will be stored in the new LocalStack sample-bucket

Let’s now create a new Article with an image:

We can view the image thanks to the previously configured entry in /etc/hosts for the localstack hostname. This ensures that the image’s src attribute, pointing to:

https://[ddev-project-name].ddev.site/s3/files/styles/wide/s3/2024-12/image.webp?itok=_NXZWAN7

Which is redirected with a 302 to:

http://localstack:4566/sample-bucket/styles/wide/s3/2024-12/localstack.png.webp?itok=_NXZWAN7

On the other hand, we can also see that the image and its image styles are effectively stored in the bucket:

docker exec -ti ddev-drupal11-localstack-localstack bash

awslocal s3api list-objects --bucket sample-bucket

{
    "Contents": [
        {
            "Key": "2024-12/localstack.png",
            "LastModified": "2024-12-19T18:26:47.000Z",
            "ETag": "\"d7cbf11f95e7d277c8989d2e8a11267f\"",
            "Size": 11510,
            "StorageClass": "STANDARD",
            "Owner": {
                "DisplayName": "webfile",
                "ID": "75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a"
            }
        },
        {
            "Key": "styles/thumbnail/s3/2024-12/localstack.png.webp",
            "LastModified": "2024-12-19T18:26:47.000Z",
            "ETag": "\"34ab21d0998bd749a7cfe82085ca6f76\"",
            "Size": 780,
            "StorageClass": "STANDARD",
            "Owner": {
                "DisplayName": "webfile",
                "ID": "75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a"
            }
        },
        {
            "Key": "styles/wide/s3/2024-12/localstack.png.webp",
            "LastModified": "2024-12-19T18:26:55.000Z",
            "ETag": "\"4f4f644fc0a98604de82e58b720af7cb\"",
            "Size": 3212,
            "StorageClass": "STANDARD",
            "Owner": {
                "DisplayName": "webfile",
                "ID": "75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a"
            }
        }
    ],
    "RequestCharged": null,
    "Prefix": ""
}

docker exec -ti ddev-drupal11-localstack-localstack bash

awslocal s3api list-objects --bucket sample-bucket

{
    "Contents": [
        {
            "Key": "2024-12/localstack.png",
            "LastModified": "2024-12-19T18:26:47.000Z",
            "ETag": "\"d7cbf11f95e7d277c8989d2e8a11267f\"",
            "Size": 11510,
            "StorageClass": "STANDARD",
            "Owner": {
                "DisplayName": "webfile",
                "ID": "75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a"
            }
        },
        {
            "Key": "styles/thumbnail/s3/2024-12/localstack.png.webp",
            "LastModified": "2024-12-19T18:26:47.000Z",
            "ETag": "\"34ab21d0998bd749a7cfe82085ca6f76\"",
            "Size": 780,
            "StorageClass": "STANDARD",
            "Owner": {
                "DisplayName": "webfile",
                "ID": "75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a"
            }
        },
        {
            "Key": "styles/wide/s3/2024-12/localstack.png.webp",
            "LastModified": "2024-12-19T18:26:55.000Z",
            "ETag": "\"4f4f644fc0a98604de82e58b720af7cb\"",
            "Size": 3212,
            "StorageClass": "STANDARD",
            "Owner": {
                "DisplayName": "webfile",
                "ID": "75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a"
            }
        }
    ],
    "RequestCharged": null,
    "Prefix": ""
}

Conclusion

Having a local implementation of AWS services is incredibly helpful for development purposes. This applies not only to the S3 service but also to the wide range of complex services supported by LocalStack. Using LocalStack can prevent unnecessary expenses—potentially significant ones—caused by mistakes during development.

In this guide, we focused solely on the S3 service and demonstrated the simplest configuration method. However, with a more advanced understanding of Docker Compose, it’s possible to design and implement a fully-featured local AWS cloud infrastructure to meet even the most complex development needs.

The post Bring the AWS Cloud to Your Desktop with LocalStack™, DDEV and Drupal appeared first on Víctor Dorado.

However, adhering to agreed-upon rules isn’t always easy. With many conventions to remember, we need tools to assist us. This is where our quality tools come in. They provide a powerful toolkit to ensure that our coding standards and style agreements are met. Furthermore, we can configure PHPStorm to use these tools, creating an integrated in-editor coding experience.

In this article we will be working on a Drupal project, but the process is applicable to any project type, as long as we will be using standard npm/yarn and Composer package management to get the tools.

Installing PHP_CodeSniffer

We will install it with Composer, as usual for many other PHP packages. We will also use a handy tool to ease the installation process.

#ddev composer require --dev squizlabs/php_codesniffer dealerdirect/phpcodesniffer-composer-installer drupal/coder

After that, as the documentation states (https://packagist.org/packages/dealerdirect/phpcodesniffer-composer-installer) we must ensure the following config is present in our composer.json:

{
    "config": {
        "allow-plugins": {
            "dealerdirect/phpcodesniffer-composer-installer": true
        }
    }
}

If we are using Composer < 2.2 it won’t and we will have to add it with the following command:

# composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true

After that, we will let the magic happen:

# composer install

Now, we can execute the phpcs command inside our DDEV web container:

# ddev exec phpcs --version
Registering sniffs in the PEAR standard... DONE (28 sniffs registered)
PHP_CodeSniffer version 3.10.1 (stable) by Squiz and PHPCSStandards

Note that PHP_CodeSniffer says something about a “standard”. PHP_CodeSniffer checks our code against one of various possible “standards”, and there are some of them bundled by default with it. The default standard that will be used is the “PEAR” one.

But, for a Drupal project (a website, a theme, a contrib module… etc.), we must use a special crafted standard called “Drupal”, that has all the Drupal community-agreed coding standards. Thanks to our previously installed dealerdirect/phpcodesniffer-composer-installer, we can see that the standards “Drupal” and “DrupalPractice” are installed:

# ddev exec phpcs -i
The installed coding standards are MySource, PEAR, PSR1, PSR2, PSR12, Squiz, Zend, Drupal, DrupalPractice, VariableAnalysis and SlevomatCodingStandard

(DrupalPractice is a more exhaustive standard that checks not only the coding style used, but also some best practices for Drupal development).

In this article, we will focus in the use of PHPCS through the UI, that is what will make a more “realtime” development experience. Using phpcs from the command line is harder, and is often only used by cli scripts, like in CI environment QA tests, or s Git precommit hook in a local development environment.

Integrating PHP_CodeSniffer with PHPStorm

PHPStorm has friendly configuration dialogs for some popular quality tools, and one of them is PHPCS.

Is highly recommended executing PHPCS inside our DDEV container, in order to keep consistency with our project’s PHP version and configuration instead of relying on our own machine config. To do so, first we must have a PHPStorm “DDEV” PHP interpreter (check my previous article PHPUnit up and running with Drupal, DDEV and PHPStorm to know how to accomplish it).

Then, go to Settings, under the “PHP – Quality Tools” section, and open the first accordion, setting its configuration and options as follows:

Notice that Drupal Core uses a different more relaxed standard. If you are going to develop for core you should set the coding standard to “Custom” and point to your project’s <drupal-root>/core/phpcs.xml.dist

You can also configure some additional inspection settings in the “Editor – Inspections” menu:

Once configured, edit any file and PHPStorm will automatically execute PHPCS, showing the warnings and errors in that file.

Conclusion

Maintaining a consistent code style in our projects is made easier with these supportive tools. Including them in every developer’s toolkit is highly beneficial.

The post Improve your code quality from PHPStorm with PHP_CodeSniffer appeared first on Víctor Dorado.

First step: enabling DDEV integration plugin for PHPStorm

DDEV has a PHPStorm plugin that eases a lot working with DDEV. One of the great things DDEV’s plugin does is creating a CLI interpreter that executes PHP code inside the web container. This will be the cornerstone of our setup.

Setting DDEV as the project’s CLI interpreter and the Test framework interpreter

Under Settings -> PHP section, we can now select the DDEV CLI interpreter:

If you don’t see the interpreter, check that you have a Docker connection added in Build, Execution, Deployment -> Docker:

And check that “Use Compose V2” is enabled under the Tools subsection:

Now, we must go to PHP -> Test Frameworks and add a new one that uses the DDEV CLI interpreter:

We must also set a custom Default configuration file named phpunit.xml and located in our project’s root directory. DDEV’s CLI interpreter runs inside the web docker container, so we must set the path as it’s seen inside the container: /var/www/html/phpunit.xml. (this file doesn’t exist yet, we will create it later).

Now, we have to tell PHPStorm to run this project’s tests with this new test framework. Go to Run -> Edit configurations menu and clear any configuration you may find here.

Then, click on Edit configuration templates… -> PHPUnit and set DDEV as the Command Line Interpreter:

Creating project’s PHPUnit configuration file

Copy core’s PHPUnit configuration file /web/core/phpunit.xml.dist to /phpunit.xml, and edit it as follows:

<?xml version="1.0" encoding="UTF-8"?>

<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         bootstrap="web/core/tests/bootstrap.php"
         colors="true"
         beStrictAboutTestsThatDoNotTestAnything="true"
         beStrictAboutOutputDuringTests="true"
         beStrictAboutChangesToGlobalState="true"
         failOnWarning="true"
         printerClass="\Drupal\Tests\Listeners\HtmlOutputPrinter"
         cacheResult="false"
         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd">
  <php>
    <ini name="error_reporting" value="32767"/> <!-- 32767 = E_ALL. -->
    <ini name="memory_limit" value="-1"/>
    <env name="SIMPLETEST_BASE_URL" value="http://my-project.ddev.site"/>
    <env name="SIMPLETEST_DB" value="mysql://db:db@db:3306/test"/>
    <env name="BROWSERTEST_OUTPUT_DIRECTORY" value=""/>
<!--    <env name="SYMFONY_DEPRECATIONS_HELPER" value="weak"/>-->
  </php>

  <testsuites>
    <testsuite name="unit">
      <directory>web/modules/custom/*/tests/src/Unit/</directory>
    </testsuite>
    <testsuite name="kernel">
      <directory>web/modules/custom/*/tests/src/Kernel/</directory>
    </testsuite>
    <testsuite name="functional">
      <directory>web/modules/custom/*/tests/src/Functional/</directory>
    </testsuite>
    <testsuite name="functional-javascript">
      <directory>web/modules/custom/*/tests/src/FunctionalJavascript/</directory>
    </testsuite>
  </testsuites>

  <listeners>
    <listener class="\Drupal\Tests\Listeners\DrupalListener">
    </listener>
    <!-- The Symfony deprecation listener has to come after the Drupal listener -->
    <listener class="Symfony\Bridge\PhpUnit\SymfonyTestsListener">
    </listener>
  </listeners>

  <coverage>
    <include>
      <directory suffix=".php">web/modules/custom/*/src</directory>
    </include>
  </coverage>

</phpunit>

These are all the customizations that have been made:

1. Adjust the boostrap path to core’s bootstrap

bootstrap="web/core/tests/bootstrap.php"

2. Set site URL and database connection details (for Kernel, Functional… etc. tests). Note that PHPUnit will be executed inside the web container, so we must set “db” and port 3306 as our database host, as it is seen from the web container. We also set the testing database name to “test”, that is the convention.

<env name="SIMPLETEST_BASE_URL" value="https://my-project.ddev.site"/>
<env name="SIMPLETEST_DB" value="mysql://db:db@db:3306/test"/>

3. Finally, we adjust all test suites to only execute tests from our custom modules by default, if we execute phpunit without file parameters nor filters.

<testsuite name="unit">
  <directory>web/modules/custom/*/tests/src/Unit/</directory>
</testsuite>
<testsuite name="kernel">
  <directory>web/modules/custom/*/tests/src/Kernel/</directory>
</testsuite>
...

Installing PHPUnit

As simple as installing these packages with Composer

# ddev composer require --dev \
  phpunit/phpunit \
  phpspec/prophecy-phpunit \
  symfony/phpunit-bridge \
  dmore/chrome-mink-driver \
  behat/mink-browserkit-driver \
  behat/mink-selenium2-driver \
  mikey179/vfsstream

• phpunit/phpunit – The PHPUnit core package.
• phpspec/prophecy-phpunit – The Prophecy mocking system. In a lot of tests it is used instead of PHPUnit Mock Object Framework, the PHPUnit standard.
• symfony/phpunit-bridge – Bridges the gap between Symfony and PHPUnit.
• dmore/chrome-mink-driver – Required for some Kernel nad Functional tests.
• behat/mink-browserkit-driver – Required for some Functional tests.
• mikey179/vfsstream – Some tests make use of this virtual filesystem mocker.

Configuring DDEV Selenium Standalone Chrome

This config is necessary to execute Javascript and FunctionalJavascript Drupal tests. PHPUnit needs a headless Chromium browser to control and to send commands to. That’s what this DDEV addon provides.

Follow the instructions in https://github.com/ddev/ddev-selenium-standalone-chrome:

# ddev get ddev/ddev-selenium-standalone-chrome

Then, update your .ddev/config.selenium-standalone-chrome.yaml and set the local domain for your DDEV project, making sure you set it as http:// and not https:// (I got an “invalid cookie domain” error when I did).

#ddev-generated  <- REMOVE THIS LINE

...

- SIMPLETEST_BASE_URL=http://my-project.ddev.site

...

- DRUPAL_TEST_BASE_URL=http://my-project.ddev.site

...

- DTT_BASE_URL=http://my-project.ddev.site

Then, restart DDEV:

# ddev restart

Executing tests from the command line

If we want being able to execute our tests easily from outside the web container, we must create the file /.ddev/commands/web/phpunit with this content:

#!/bin/bash

phpunit "$@"

And now, outside the web container, we can do:

# ddev phpunit
# ddev phpunit --testsuite <name>

Executing tests from PHPStorm

From PHPStorm’s interface, we can go to any test case class and use the GUI to run its tests, either all at once or one by one, simply clicking on the run icons next to the class and test method definitions:

We can even right click on any directory in the project’s explorer and click on “Run (tests PHPUnit)” and all tests in that directory will be executed. This is very convenient when we want to debug only a test method or execute only one type of tests inside a module, for example.

Conclusion

Getting PHPStorm, DDEV, Drupal and PHPUnit to work together is not a trivial task. Although DDEV’s PHPStorm plugin eases a bit the task, we have yet to wire all the things correctly.

The post PHPUnit up and running with Drupal, DDEV and PHPStorm appeared first on Víctor Dorado.

If you also add DDEV and its docker containers to the mix, it’s not easy to get all pieces working, without a proper recipe. This article aims to be that recipe.

Preparing DDEV’s web container

DDEV automatically adds two environment variables to its .ddev-docker-compose-base.yaml file:

PHP_IDE_CONFIG=serverName=${DDEV_SITENAME}.${DDEV_TLD}
DRUSH_ALLOW_XDEBUG=1

Mind the serverName because we will need it later, when configuring a server in PHPStorm.

Now, we must config the Xdebug PHP extension. Create a new directory .ddev/php/ and create a file called xdebug.ini inside it, with this content.

xdebug.client_port = 9000
xdebug.idekey = PHPSTORM
xdebug.mode = develop,debug
xdebug.start_with_request = yes

I like to set xdebug.start_with_request=yes and turn on and off the web contaniner’s xdebug PHP extension with ddev xdebug on and ddev xdebug off. You could set xdebug.start_with_request=no and play with a browser switch like Xdebug Helper, but this won’t have effect on drush commands.

After that, we have to restart DDEV’s web container:

# ddev restart

Configuring PHPStorm

Now, we must create a new PHP server under Settings -> PHP -> Servers. Recall the server name we saw in DDEV’s config: it was ${DDEV_SITENAME}.${DDEV_TLD}, that translates to my-project.ddev.site if your DDEV project is named my-project.

We need to set path mappings for the webserver docroot directory. A path mapping “maps” a real directory path in your filesystem with a directory inside the DDEV docker web container. In our case, a DDEV drupal project has its web server’s document root in /var/www/html/web, so we have to set this mapping:

• /path/to/your/project/web -> /var/www/html/web

However, I recommend also adding this mapping to be able to debug vendor code.

• /path/to/your/project/vendor -> /var/www/html/vendor

With these mappings, PHPStorm now knows how to map between the same file as it’s seen inside/outside DDEV’s web container.

After that, to be sure everything is ok, I recommend checking and configuring the Xdebug installation under PHP -> Debug:

First, click on the “Validate” link:

In the next screen configure the docroot directory as it’s seen by PHPStorm (your real machine path to the web directory inside your project directory) and the URL where the project’s docroot will be accesible. Then, click on “Validate”.

I strongly recommend unchecking these two “Force break” checkboxes, because we don’t want the execution to be paused if we don’t set or don’t reach a breakpoint. I remember myself waiting a drush command to finish unaware that the execution was paused, because of this.

So far, we have configured DDEV and PHPStorm to “connect” between them and our next step will be to set a breakpoint. For example, we can break on the handle() call that Drupal\Core\DrupalKernel class does on every page load.

Click next to the line number and a red dot will appear. This is our breakpoint. The PHP execution will stop here until we let it continue.

Remember to enable xdebug PHP extension on DDEV’s web container with

# ddev xdebug on

And to tell PHPStorm to listen to incoming debug connections with the icon.

Now, reload any page in your browser and you will view a system notification letting you know that PHPStorm requires your attention. Go for it and you will see the breakpoint’s line highlighted and a panel where you can explore all the variables in it’s scope.

You can browse the variables panel and deep dive into the tree structures. This is VERY useful, specially when debugging a framework like Drupal that has many nesting levels on its variables.

You can also select any piece of code, right click on it and click on “Evaluate expression” and you could test it inside that paused execution state. You can even write directly your own expressions.

You can continue the execution step-by-step (step over, F8), even traveling inside method calls (step into, F7), or continue the execution until the next breakpoint (or the same breakpoint if it’s reached again)

Conclusion

Debugging goes next level when it’s done with a tool like Xdebug and through a debugging GUI like PHPStorm has.

The post Debug your Drupal code with PHPStorm, DDEV and Xdebug appeared first on Víctor Dorado.

I have to say that, now that the project has evolved and I can have an overview of it, I think we could not have implemented all the complexity of the business logic without this design pattern. In my opinion, it is a fantastic way to organize the code, although it has some problems that must be taken into account.

Why wrapped entities and not bundle classes?

Mateu Aguiló explains it perfectly in the Typed Entity module page: Bundle classes may seem attractive at first, but they have disadvantages: they carry on all the complexity of EntityInterface, making it hard to do tests with them.

However, wrapped entities use the facade pattern, which hides all the complexity of EntityInterface, leaving a clean object that is much easier to test and mock.

Repositories? Active Record pattern?

It is very convenient to use the Active Record pattern this way:

$owner = $book->owner();

But, if not implemented well, this pattern has its drawbacks in terms of testing the code. Fortunately, there are some solutions, and one of them is to pass as a dependency the repositories that the entity will use to get the related entities. This has a drawback: if the Book entity is related with many other entity types, then we will have a lot of dependencies (one for each of the repositories that allow obtaining those entities)

$bookRepository = \Drupal::service('model.book.repository');
$authorRepository = \Drupal::service('model.author.repository');
$libraryRepository =\Drupal::service('model.library.repository');

$book = new Book(
  $bookRepository,
  $authorRepository,
  $libraryRepository
);

$author = $book->author();
$library = $book->library();

Typed Entity module solves this problem using a “Repository Manager”, which becomes a single dependency and is in charge of wrapping an entity with its wrapped entity facade object.

class WrappedEntityBase {
  ...
  
  public function wrapReference(string $field_name): ?WrappedEntityInterface {
    $target_entity = $this->getEntity()->{$field_name}->entity;
    return $this->repositoryManager()->wrap($target_entity);
  }
  
  public function owner(): ?WrappedEntityInterface {
    $owner_key = $this->getEntity()->getEntityType()->getKey('owner');
    if (!$owner_key) {
      return NULL;
    }
    return $this->wrapReference($owner_key);
  }
  
  ...
}

We can see an example of this in the WrappedEntityBase base class, that has an owner() method that makes use of the repository manager to obtain the entity. This, in turn, uses a wrapReference() utility method that wraps an entity related through any EntityReferenceField.

Note: At the time of writing, in the Typed Entity module, the repository manager is not an injected dependency and is being obtained through a .module function. I think it could be because most of the module tests are Kernel tests, and this way things are simpler.

Although the owner() function example is a bit confusing (because it uses the EntityType definition element to get the field name), in our custom entities we can do something as simple as this:

class Book extends WrappedEntityInterface {
  
  public const FIELD_LIBRARY = 'field_library'
  
  public function library(): ?WrappedEntityInterface {
    return $this->wrapReference($self::FIELD_LIBRARY);
  }

}

Advanced use of repositories and Query Objects

If we want to get our wrapped entities from our repositories using a query analogous to how we would do it with the Entity Query API, we start to see an old known repositories problem: the repository interface starts to be cluttered with many findBySomething() methods.

To avoid this, in my “custom adventure” (without using Typed Entity) I was able to implement the Query Object pattern, so that a “query object” is prepared and then passed as a parameter to a repository. This is a much smoother way of working, as it can be seen in the following example:

// Given this library wrapped entity (it does not matter now how it's created).
$library = ...

// And a featured book.
$featuredBook = ...

// We can get all the other books from the library
$otherBooks = $this->bookRepository->get(
  BookQuery::new()
    ->relatedWith($library)
    ->notEquals($featuredBook)
    ->sort('DESC', Book::FIELD_NAME_DATE)
    ->range(0, 10)
);

The QueryBase class (from which BookQuery extends) has several utility methods that can be used to communicate very expressively with repositories, giving them precise selection, sorting and paging instructions.

Here are some examples:

Identity:

idIn(array $entityIds)
idNotIn(array $entityIds)

Relations:

relatedWith(WrappedEntity $entity)

Perhaps this method is the most curious, since it uses the entity’s field definitions to find automatitically the entity reference fields that relate to the entities of the concrete WrappedEntity child passed as parameter.

Dates:

current()
past()
future()
fromDate(DrupalDateTime $date)
toDate(DrupalDateTime $date)
betweenDates(DrupalDateTime $from, DrupalDateTime $to)

(current(), past() and future() are possible by using a unique date range field for all entities):

Result control:

sort(string $direction = 'ASC', ?string $fieldName = NULL)
range(?int $start = NULL, ?int $length = NULL)

We aren’t limited to these base query object utility methods. We can extend the BaseQueryObject with a BookQueryObject that could have custom entity specific conditions.

$bestSellers = $this->bookRepository->get(
  BookQuery::new()
    ->purchasedAtLeastNtimes(100)
);

Conclusion

As you can see, the use of query objects is a great advance in clarity and expressiveness of the code, although it does not solve all cases. For those special cases, we can always continue using a getBySomething() in the repository.

The post Query objects, the brand new form of getting your typed entities appeared first on Víctor Dorado.