DEV Community: Sergey Tolkachyov

Process Forge: a framework for creating AI processes

Sergey Tolkachyov — Fri, 07 Aug 2026 05:55:40 +0000

During the 2026 New Year holidays, in one of the Joomla community chats, a fellow colleague shared a prompt for an AI agent and the result of that prompt. A week before that, he had tried Gemini CLI for the first time. Until then, I had only used AI in web versions, and overall that suited me fine. When I saw that wall of text, the CLI request, and the wall of response, the first thing that hit me was:

I DO NOT WANT to learn all this stuff! Something new again, I'm tired of it...

Then came the stages of trial and error, attempts to use ready-made community skills packages from GitHub with role-based suggestion like

"you are a super-duper mega-backend Joomla developer with 40 years of experience, make it beautiful for me"

Somewhere in the middle of this half-year I started formalising my processes. And by processes I do not mean only development, but also SEO, analytics, business analysis, process study and process design, and so on. In the end, as a rule, all of that is either connected with or leads to a Joomla site. Formalisation brought me to an understanding of several basics that are common to all processes. More on that below.

Now I want to present to the honourable public my work on a framework for creating formalised work processes for AI agents: Process Forge (GitHub).

I ask experienced vibe coders to forgive me in advance for any obvious points or long-known theses if they appear here. Workload did not allow me to spend too much time searching and watching what others were doing. I had to switch myself onto new tracks.

Starting Points

To answer the questions "what is all this for?" and "why this way?", I will give several starting points that I mostly felt out through practice over these six months and from which I proceeded when creating Process Forge. Some of these conclusions later found confirmation in other people's findings that I noticed in articles or social media posts:

An AI model's internal knowledge about a technology stack is most often seriously behind real modern practice. This varies a lot from stack to stack. You can add "for now", but in general this is still a relevant premise.
For an AI agent to work properly, it needs to be given everything a human is given for work: knowledge and tools, ready-made templates for reuse.
An AI agent needs a certain amount of freedom, but within a defined corridor, along a specified vector.
You must not be tied to any one AI provider ecosystem. There must be a way to "switch the brains" (there should be no .codex, .claude, and so on as the agent's home base; there should be something neutral, even though the agents themselves try to bind you to their ecosystem).
All project memory and processes must be structured in files.
You yourself must first understand WHAT is happening, HOW, and WHY. Without that, AI will only bring more chaos into your life.

When we work with AI agents, and with AI in general, we expect the work to be done quickly and well, because this is Artificial, damn it, Intelligence. But it turned out not to be so. Instead of a shovel, you were given a turbo-excavator that says to you: "I am ploughing the field, my wheel fell off, I will quickly fix it with a temporary fallback and put a track on one side." You still have to learn how to work with this thing, and know where and how to apply it properly. I should say right away that almost everything written here is the result of my own heuristics and is therefore purely subjective. Only several months later did I get acquainted with AI Factory (link one, link two (Habr)) and GSD Core, but it was already too late, because I was already working full steam with my own tool. There may well be other similar tools.

Process Forge Concepts

I will lay out the concepts in the order in which they appeared and were tested in "combat" conditions as they evolved. This way the history and logic of the decisions will be clearer.

Process Instead of Chat

After two months of working in chat mode and with ready-made community skills packages from GitHub, with role-based suggestion like "you are a super-duper mega-backend Joomla developer with 40 years of experience, make it beautiful for me", a quick search and a discussion with AI about my own doubts around all of this led me to the conclusion that I needed to build a development process. At first, only for development.

Chat history cannot be a reliable source of project data or project memory. Every new session starts from zero for the agent: tabula rasa. The agent has to be loaded with project context: what this thing is and how to deal with it. That is why all project memory and processes must be structured and stored in files. In spring I came across the word "artifact" in the sense of "a file produced as the result of an autonomous process". As far as I can judge by what is happening in the industry, everyone is accumulating their own Markdown files: in folders, in Obsidian, or somewhere else, with different instructions, skills, and so on inside.

My request was immediately for a process, so after several days of discussion I arrived at an artifact-based development flow. It was a set of folders and files describing the rules for working with projects. They described the workflow stages that I used and improved over three months while creating Joomla libraries, plugins, and components. You can get a general sense of the stages under the cut. In a modified form, this entered Process Forge as one of the "out-of-the-box" processes.

Example process stages:

Stage	Meaning	Requires	Fills
`artifact-policy`	Normalises artifacts before the stages	`task-record`, `project-context`	`artifact-index`, `missing-artifacts-created`
`flow-orchestrator`	Chooses the current/next stage	`task-record`, `artifact-index`, `project-context`	`stage-decision`, `next-skill-handoff`
`intake-scope`	Records the task, boundaries, and success criteria	`task-request`, `project-context`	`brief`, `scope`, `task-record`
`investigation`	Gathers facts, causes, and the impact surface	`brief`, `scope`, `project-context`	`investigation-report`, `impact-analysis`
`domain-surface`	Describes domains, ownership, and risks	`scope`, `investigation-report`, `impact-analysis`	`decision-log`, updated `impact-analysis`
`architecture-plan`	Designs the solution and the order of changes	`brief`, `scope`, `decision-log`, `impact-analysis`	`architecture`, `implementation-plan`
`implementation`	Makes changes according to the plan	`architecture`, `implementation-plan`, `decision-log`	`changed-files`, `change-summary`
`code-assurance`	Checks, review, test cases, browser proof	`changed-files`, `change-summary`, `implementation-plan`	`review-findings`, `test-plan`, `test-cases`, `browser-verification-report`
`release-delivery`	Release packaging/delivery	`change-summary`, `review-findings`, `test-cases`	`release-notes`, `migration-notes`, `patch`
`evolve`	Extracts reusable lessons into rules/extensions	`patch`, `evolution-cursor`, `logs`	`evolution-report`, `updated-rules-or-extensions`, `updated-cursor`

This is one of the earlier versions of the artifact-based development flow.

In addition, the whole flow maintained task-log, agent-log, verification-log, and tool-telemetry.ndjson; the specific log depended on the stage. Telemetry records tool usage and the reasons for using those tools. For example, if MCP PhpStorm could not perform the required action or got stuck for some reason, plain shell was used as a fallback.

Connecting Knowledge to an AI Process

The knowledge built into AI models themselves usually lags behind current reality. Top paid models have some idea of recent events, but even then not always. In my subjective assessment, web search also costs AI agents more time and tokens, so all current knowledge should be close at hand, and the agent should build its context from it. Almost anything can be used as reference material:

source code of current versions,
snapshots (local copies) of official documentation,
your own or other people's development articles,
your notes with recipes for solving a particular task,
links to sites.

I work with Joomla, so in my stash I have:

source code of several Joomla core branches,
source code of the main Joomla extensions I work with regularly (JoomShopping, RadicalMart, and so on),
copies of official documentation for web full stack: manual.joomla.org, HTML / CSS / JS / PHP, and documentation for several frameworks,
my own articles and some articles by fellow colleagues,
documentation for various APIs, which I supplement with dumps of real responses if it is REST,

and so on. Yes, I know that Context7 exists (the service and MCP for machine documentation), but as far as I remember it started limiting requests at some point and, predictably, introduced pricing plans with request packages.

Overall, this section of the article lives in the plane of on-premise vs SaaS: either we do it ourselves for ourselves, by hand; or someone else does it for us, but for money. For now I am, as you have probably already guessed, a supporter of the former )) Naturally, with this approach you, or your AI agent, take on the obligation to keep knowledge up to date.

Connecting Tools, MCP, and Templates

Templates

I will start with templates because they are simple: in my case these are separate ready-made pieces of code that can be copied, slightly adapted, and they are ready. For an AI agent, it is better to put them into folders and give each folder a README.md describing what this template is and how to work with it.

But it does not have to be only code: design fragments, video fragments (footage), and so on. Whatever your agent works with.

Tools and MCP

By tools I mean what the AI agent can use on your device. For a developer this may include git, GitHub CLI, pipeline runs, linters, fixers, packagers/builders, local and remote test stands. For an SEO \ GEO specialist these may be small utilities for automated access to various service APIs (Yandex APIs for Wordstat and SERP data collection), Screaming Frog CLI, and so on. I suppose that a conventional video-production setup also has similar tools of its own.

The most important point is that the tool must be configured globally on the workstation so that different projects can use it in the same way: one builder instance is used across all 80 plugins you write.

MCP in this case appears as the same kind of tool, just available through Model Context Protocol. It may be Playwright / Chrome DevTools / Firefox DevTools for tasks that require a browser. It may be MCP IDE PhpStorm in my case, Serena for symbolic code analysis, and so on.

I noticed that when working with code through MCP IDE, there are fewer problems with file encodings and file-system permissions. Also, through MCP the agent can receive more information from inspections and run tests. But it can also run shell commands through the PhpStorm console, even though it already has direct access to the console, so catch it in time before it starts doing nonsense.

Processes Again

In the context of working with Joomla and its extensions, I try to work through a full engineering process: the required functionality is discussed, we plan the implementation, then write the code, run end-to-end tests, finalise and build the package, and publish a release according to semver. After that, post-release tasks roll in: update or write documentation from scratch in two languages, prepare screenshots in two languages, video in one language, publish announcements about new versions with descriptions on 15+ platforms...

As I came to understand how to work with AI agents, the results of our joint work started accumulating. A new problem appeared: when should all this be checked and published? With agents, less time was spent on code, but more time on planning and testing. And post-release tasks did not disappear...

So the next experiment was to try adapting the agent for writing documentation, preparing screenshots, and publishing all of this to the site. The file-based process that had already been worked out handled this too. With great distrust, over several dozen iterations, I began expanding the agent's area of responsibility and eventually reached full release publication. In general it works, but there is of course less human spirit in it than one would like.

Often, certain thoughts or pieces of information circle around us for a long time, appearing before our eyes several times before we notice and understand them. In this case, an understanding began to form that I was surrounded by processes of different complexity in my work. It became logical to go one level above coding and identify a universal process entity, where there may be different numbers of stages, artifacts between them, relationships, and so on. That is how Process Forge began to appear.

It now has internal processes, out-of-the-box processes, and the ability to create your own processes. Processes can branch, and a parent process can wait for the results of a child process and then continue working.

Platforms and Specialisations

Platforms

The platform entity allows Process Forge knowledge packages to be combined into pluggable packages, and lets you describe the execution environment, templates, and required tools inside them. When you start making "a new plugin for Joomla 6+ that...", the agent understands which platform is meant and adds not only Joomla knowledge to the project context, but also PHP, HTML, CSS, JS knowledge, the required checks package, code style rules, and the Phing extension packager.

Platforms can inherit from one another. For example, you are writing a plugin for the JoomShopping online store, which does not exist separately from Joomla. But JoomShopping has its own separate knowledge sets, which are not needed when working on the clean engine core or another store. And, predictably, when working with JoomShopping we also need knowledge about Joomla.

Specialisations

If our agent writes Joomla code, it needs knowledge for writing code. But if it publishes an article or works with modules on the site in the admin panel, it does not need PHP, JS, or Joomla extension architecture knowledge. It needs knowledge of the admin panel, of the REST API for faster work, maybe basic HTML and the CSS framework of your project's site, image-processing rules, media-content placement rules (what to put in which folder), and so on. That is why specialisations appeared: they combine the knowledge needed for a particular specialisation.

The point of this entity is that the backend may work with Joomla, or with Laravel, or with Django and Python. Platforms provide applied knowledge about the language, architecture, and tools. Specialisations provide general abstract context: patterns, approaches, principles. Specialisations may also connect their own knowledge, tools, templates, MCP, and so on.

Cascading Project Context Computation

In Process Forge, context is not stored in one large prompt or skill. It is computed as a cascade from several levels, by analogy with merging arrays/objects: each next level inherits the data from the previous ones and refines it for a specific situation.

General workspace rules are supplemented by company, area, platform, and project knowledge, then by process, task, and concrete agent settings. More local levels can extend or override general parameters. As a result, the agent receives not the entire accumulated mass of information, but the relevant context assembled immediately before the task is performed.

In general terms, the context-computation logic is as follows:

Workspace
Company / organisation
Area (SEO, development, content...)
Platform (Joomla, WordPress, Symfony...)
Specialisation (backend, frontend, full stack, content, SEO...)
Project
Process (software development / SEO audit / ...)
Task and current stage
Agent role and profile (in multi-agent mode)

Each next context source is layered over the already assembled one. The result of this work is a project context snapshot (YAML for machines, Markdown for people), which states:

platform_contracts / platform_stack: selected and available platform contracts
resolved_parameters: final parameters after inheritance and overrides
parameter_resolution: parameter sources, provenance, and conflicts
resolved_context: the result of specialisations, resources, tools, MCP, templates
resolved: final knowledge packages / resources / templates / tools / processes
capabilities: required/optional capabilities and their status
conflicts: specialisation and parameter conflicts
snapshot.health.status: final state: pass, warn, or blocked
freshness / context_policy: freshness policy and state

and some other information.

For a specific task, and in multi-agent mode, even more specific snapshot-capsules are assembled and passed to the agent together with its assignment / process / stage / task layers as machine-readable files.

The General Feedback Mechanism: Evolve

Evolve in Process Forge collects useful conclusions that appeared during work on a task: what should be remembered, improved, checked, or moved into shared experience. It does not change rules and knowledge automatically. First, it formalises such findings as proposals with a clear scope: only for this project, for the workspace, for a package, platform, or the core. Then those proposals can be checked, selected, and only then consciously included in shared materials or updates.

When a proposal turns into an updated knowledge package, template, rule, or other shared material, it is distributed through the normal Process Forge update mechanism. The project sees that an update is available, can prepare it, check it, apply it, and after that rebuild its context with the new version of shared knowledge.

Versioning

Both Process Forge itself and its entities are designed with versioning in mind. Since everything lives as files, as separate packages, you can gradually improve and expand them. Accordingly, you can have your own update server for all parts of your workplace: the Process Forge core, separately processes and platforms, separately knowledge packages and templates. For example, you made process changes after evolve from several machines: you publish a new process version. You created new instructions for working with code: you publish code_instructions_v.1.1.0, and all your workstations receive a new knowledge package. After that, local workers update project contexts and can work with the new knowledge.

Organising Work in Process Forge

In a surprising way, all of this starts to resemble structures built in human companies and organisations. I assume that the human operator should not have to know slash commands, but should simply direct agents in natural language. That is why Process Forge 2 has documentation both for people and for agents.

To get started, you need to set up your machine:

Install the ProcessForge distribution (unpack the archive into your agent area).
Run step-by-step workplace setup with a human involved (there is an auto mode, but at your own risk).
Configure path constants and root directories.
Specify roots for knowledge and local documentation.
Register tools and MCP servers.
Create or import knowledge packages.
Create a registry of reusable templates.
Create platforms from existing resources.
Create specialisations.
Connect project(s) to the workplace.
Create your own processes if the out-of-the-box ones are not enough.
Start working.

Yes, this takes time to set up the machine. But it scales, and in general it has shown itself fairly well.

Process Forge assumes two main operating modes: garage mode and forge mode.

Garage Mode (1-1-1-1)

This is the mode where there is:

one human operator,
one main agent session (console window),
one project,
one active process/run.

The main agent performs the work, runs checks, maintains artifacts, and either finishes the work or hands it off to the next stage or process.

We open a console / chat with the agent, say "immerse yourself in the project through .pf. Tell me what has been done and where we stopped?", and continue working within one project. Physically, you may have two or three independent projects open at the same time, each working in garage mode. And in this garage you have an assistant that uses your tools, uses your knowledge, uses your platforms, and works according to your templates.

Forge / Factory Mode

This is a multi-agent mode where work is divided into independent streams.

Your main agent becomes an orchestrator that receives input data, chooses the process, creates assignments with context capsules, then starts agent sessions (full-fledged agents or subagents), coordinates them, and makes sure agents do not interfere with one another. Then it collects their results and integrates the outcome through result handoffs and reviews.

In this way, work on a project becomes similar to the work of a team or department on a project. They need to be coordinated, and therefore there appears...

Agent Director is a workplace-level role for organised coordination of several agent sessions, processes, or projects. It is not needed in garage mode, but it is needed where there are handoffs, waiting for a suitable executor, errors, parallel work by several orchestrators, or the need to explicitly transfer responsibility. Project agents and orchestrators can send signals to the Director's inbox: for example, that a task is blocked, another executor is needed, an error occurred, or an operator decision is required. Such messages form cases, which the Director takes into account during the next coordination pass.

At the same time, in the current ProcessForge implementation the Director is not a constantly running independent LLM agent. In the PF model it is described as an agent role, but it is executed as a CLI coordination layer: it checks the handoff queue, agent availability, leases, and the state of open cases, but it does not perform tasks itself and does not launch agents. In the future, this role can be developed into a full AI agent that reasons about priorities and complex routes, but for now it is a deterministic mechanism for managing workplace coordination.

The watchman's log. To make it comfortable for agents to work in a Process Forge workplace, there is a "watchman's log" where agents who have "come to work" are recorded. It shows who entered the process, what they saw, what they did, where they stopped, and what risks they left for the next participant.

The log helps quickly restore the course of work without searching through all files and messages. This is important because work can move between agents, tasks, and runs, while the log preserves context continuity. And it is not a separate agent; it is a CLI tool, so we do not spend tokens here.

Given that your computer is turning into a kind of company branch or small office, it may later have not only a Director and a watchman. Over time, it may get a "facilities manager" (some kind of background process) that checks whether anything needs to be done with the workplace: send candidates for improving knowledge packages to a central hub for release, or receive new knowledge packages and intelligently update the contexts of all projects. Or perhaps there may be a "cleaner" (a process that occasionally launches an agent for smart cleanup). But these are already fantasies, somewhat detached from reality ))

Conclusion

In some articles about AI development I have encountered similar ideas: you need to build a pipeline that performs tasks of the same type. The times, apparently, are such in AI that it is easier to create your own custom tool than to take someone else's and adapt to it, or try to customise it. Nevertheless, I will risk sharing my work with the IT community in a field that is completely new to me. I hope it will be useful to someone.

How to work with the component menu in the Joomla admin panel using preset.xml and the plugin.

Sergey Tolkachyov — Sat, 23 May 2026 16:23:17 +0000

The Joomla component has several levels of presence in the admin panel. The simplest level is created by the component installer: if the manifest contains <administration><menu>...</menu></administration>, Joomla will add the item to the protected admin menutype=main. But this is often not enough. A normal component needs groups of links, quick actions, links to categories, fields, workflow, dashboard, separate sets of items for different administrative modules, and the ability to add or hide items dynamically.
To do this, Joomla 6.1 uses the menu preset mechanism.

How to work with preset.xml and modify the admin panel menu using the plugin in this article.

Read the article (in Russian)

CFI Plugin v.2.0.0 Released - Export/Import Joomla Articles to/from CSV

Sergey Tolkachyov — Mon, 19 Jan 2026 09:44:59 +0000

This plugin allows you to export Joomla articles to a CSV file. You can then edit the data in a spreadsheet editor (e.g., Excel or Open Office Calc) and upload the file back. In some cases, this is more convenient and faster. The plugin allows exporting tag IDs, working with custom article fields in Joomla, as well as usually non-editable article properties like hits, modification date, etc.

Initial versions of the CFI plugin were created by developer AlekVolsk for Joomline. He created versions 1.0.0-1.0.16 for Joomla 3. Subsequently, in 2026, the plugin was transferred to WebTolk for further development.

v.2.0.0. What's New?

Refactoring. The plugin has been completely rewritten from scratch.
New Import/Export Interface. Export and import now open in a modal window. Functionality to select article properties, tags, and custom fields for export right before the export itself has been added.
Article Filtering During Export. You can filter the articles you need using standard search parameters in the admin panel, and then export only those: only featured ones, only published ones, only articles from 2 categories, only articles with a specific tag, etc.
Import/Export All Article Data. Previously, the plugin could only export some article data. Now, during export and import, you can change all article data found in the article editing form, even non-editable ones like hits or modification date. This way, you can quickly update all meta-descriptions or just the field data.
Import Custom Fields Only. The articleid field remains mandatory for import. Thus, you can import only custom field data without changing the article data itself.
Joomla 6. The plugin has been rewritten with the current structure for Joomla 4+ and successfully tested on Joomla 6.
For Developers: Pre-processing by Plugins. You can process data with your own plugins of the cfi group on-the-fly, directly before importing or exporting data. Events: onExportPrepareData($event) and onImportPrepareArticleData($event).

System Requirements: Joomla 4.3+, PHP 8.1+.

To update from older versions, release 1.0.16 is available, which adds a new update server.

Extension Page (https://web-tolk.ru/dev/joomla-plugins/cfi-eksport-import-materialov-joomla?utm_source=dev.to)
Extension GitHub (https://github.com/WebTolk/cfi)
Version for Joomla 3 and Joomla 4 (https://joomline.ru/rasshirenija/plugin/cfi.html)
GitHub Repository for Joomla 3+ versions (https://github.com/AlekVolsk/cfi)

Joomla View Logs component v.2.3.0 has been released!

Sergey Tolkachyov — Sun, 11 Jan 2026 11:22:44 +0000

The component allows you to view error logs and notifications in the Joomla admin panel. Logs of both Joomla itself and extensions that use the standard kernel logger are displayed. It works with Joomla 4+, Joomla 5+.

v.2.3.0 What's new?

The option to disable the display of the PHP log has been added in the component settings
Added a message about the inability to delete a PHP log from the log list page
Added a link to download the zip archive in the message about archiving the log
The disabled attribute has been added to the "archive" and "delete" buttons for the PHP log
Fixed the reading path for the PHP log
Fixed links for downloading logs in csv format from the logs list page
Fixed downloading logs in csv format from the logs page (previously logs were downloaded with html code the template)
Fixed translation of column headers of the log table

Extension page
Extension GitHub

Joomla-дайджест. 2-е полугодие 2025 года.

Sergey Tolkachyov — Sat, 03 Jan 2026 17:17:53 +0000

Все главные новости из мира Joomla с июля по декабрь 2025 года в одной статье. Я честно пытался напрячь самые разные ИИ сортировкой постов по смыслу и, к сожалению, ни один из них не справился с этой задачей так, как нужно мне. Поэтому, напрягая собственный интеллект, представляю читателю наш дайджест, который обозревает новости, расширения, шаблоны и статьи из мира Joomla.

Читать на Хабре.

WT IndexNow - send your Joomla urls to search engines via IndexNow protocol

Sergey Tolkachyov — Sat, 03 Jan 2026 09:03:05 +0000

A free package of plugins that provides manual and automatic sending Joomla URLs to search engines for reindexing using the IndexNow protocol (https://indexnow.org).

Supported components

At the moment, the package includes providers for the following components:

Joomla articles and aritcles categories
Joomla contacts and contacts categories
SW JProjects GitHub Joomla Extensions Directory
JoomShopping Joomla Extensions Directory
Phoca Download
Phoca Cart
RadicalMart

The plugin package is designed to send the URLs of Joomla sites to search engines for reindexing using the IndexNow. According to the documentation, the protocol is supported by all major search engines except Google. The protocol is used to receive URLs from sites that need to be reindexed or indexed for the first time as quickly as possible. Sending site addresses in this way will significantly speed up the indexing of new or modified content by search engines. Search engines use this protocol to exchange data with each other, so by sending a URL to one of them, you share it with everyone at once.

Using the IndexNow protocol, no more than 10000 URLs can be sent per day. Keep this in mind when working with content.

WT Yandex map items v.2.0.5 Joomla module has been released

Sergey Tolkachyov — Wed, 30 Jul 2025 05:09:25 +0000

Display data from various component's custom fields like Yandex.Maps placemarks. Joomla articles are displayed as Yandex.maps placemarks. The articles categories and contacts are not displayed yet.

v.2.0.5. What's new?

UX improving

When interacting with a page on mobile devices, if the map is displayed in full width, it starts scrolling instead of the web page. To avoid this situation, an overlay for the map has been added. Now interaction with the map is possible after clicking on the map. The overlay automatically turns on when the cursor leaves the borders of the map container and the map can be scrolled again.

Extension page
GitHub

Joomla 5.2.4 Security & Bugfix Release

Sergey Tolkachyov — Wed, 19 Feb 2025 05:23:10 +0000

Let’s celebrate! The Joomla! Project is pleased to announce the release of Joomla 5.2.4 and Joomla 4.4.11. This is a security and bug fix release for the 5.x and 4.x series of Joomla.

These releases continue Joomla’s high standards in accessible web design, highlighting Joomla's values of inclusiveness, simplicity and security into an even more powerful open-source web platform.

Security Fix

[20250201] - Core - SQL injection vulnerability in Scheduled Tasks component. Read more.

Bug fixes and Improvements with 5.2.4

Fix namespace map creation on PHP 8.4 (#44789)
Fix PHP Warning for debuguser, debuggroup (#44721)
Fix handling of null values on update row (#39607)
Fix cache counting issue - correctly count number of files (#43986)
Fix permissions for manually running scheduled tasks (#36719)
Tag Router: Allow numeric/CSV IDs (Regression) (#44784)
Fix for Composer update to enshrined/svg-sanitize to resolve SVG upload issues (#44746)
Fix for Article cannot be saved successfully on the front-end (#44680)
Fix media downloads with spaces (Follow-up of #37396) (#44745)
Finder Router: Filter out unnecessary query elements (#44055)
Jooa11y plugin and page cache conflicts (#41956)
Fix a11y issue in accordion (role attribute) (#40578)
Remove alt-text for menu items when both image and title are set (a11y fix) (#40675)
Fix breadcrumbs color in light and dark mode (#44212)
Email alt text fix in contact component (#44491)
Web Asset Manager: Incorrect loading of external resource with / at the end (#44774)
Fix media downloads with spaces (Follow-up of #37396) (#44745)
Fix multi-select behavior in Media Manager (Follow-up of #39824) (#44747)
Fix error handling when creating folders in Media Manager (#39878)
Fix assets for com_scheduler on new installations (#44684)
Fix password reset broken in backend (#44723)
Email cloak plugin fails for emails with IDN (Internationalized Domain Names) (#39888)
Fix handling of root path removal only when it is at the beginning (#36685)
Load the namespace from the cached manifest (Reverted) (#44755)
Fix for Codemirror duplicated assets entries (#44674)

The full list on GitHub is here: https://github.com/joomla/joomla-cms/milestone/136?closed=1

Joomla tip: show notifications by Joomla.renderMessages

Sergey Tolkachyov — Mon, 17 Feb 2025 13:49:06 +0000

The user performs some actions on the site and receives messages about the successful or unsuccessful result, as well as just informational messages. In php code, we are used to using the enqueueMessage() method for this.

<?php
use Joomla\CMS\Factory;

$html = 'Message';
Factory::getApplication()->enqueueMessage($html, 'warning');

Most often, language constants are used as messages so that users can receive messages in their own language:

<?php
use Joomla\CMS\Factory;
use Joomla\CMS\Language\Text;

Factory::getApplication()->enqueueMessage(Text::_('SOME_LANG_CONSTANT'), 'info');

Rendering of Joomla messages in the frontend

Here we will need the connected core files core.js and messages.js. A little excerpt from the code:

/**
 * Render messages send via JSON
 * Used by some javascripts such as validate.js
 *
 * @param   {object}  messages JavaScript object containing the messages to render.
 *          Example:
 *          const messages = {
 *              "message": ["This will be a green message", "So will this"],
 *              "error": ["This will be a red message", "So will this"],
 *              "info": ["This will be a blue message", "So will this"],
 *              "notice": ["This will be same as info message", "So will this"],
 *              "warning": ["This will be a orange message", "So will this"],
 *              "my_custom_type": ["This will be same as info message", "So will this"]
 *          };
 * @param  {string} selector The selector of the container where the message will be rendered
 * @param  {bool}   keepOld  If we shall discard old messages
 * @param  {int}    timeout  The milliseconds before the message self destruct
 * @return  void
 */

This is what it looks like in practice:

Joomla.renderMessages({
    message: [Joomla.Text._('COM_SWJPROJECTS_USER_KEYS_KEY_SUCCESSFULLY_COPYED')]
});

Now we see that we can use language constants as a message in Javascript. And that's cool! To do this, we use the Joomla.Text._() method (similar to Text::_() in PHP). But Javascript has to get the values of these language constants from somewhere. And to do this, in the php code of our page, we need to take care of it and add the language constants necessary for js using the Text::script() method.

<?php
use Joomla\CMS\Language\Text;

Text::script('SOME_LANG_CONSTANT_SUCCESS');
Text::script('SOME_LANG_CONSTANT_FAIL');

This way I can access the values of the language constants SOME_LANG_CONSTANT_SUCCESS and SOME_LANG_CONSTANT_FAIL in javascript.

Joomla Community resources

Joomla tip: Use the Joomla\Uri\Uri class to create a URL.

Sergey Tolkachyov — Thu, 16 Jan 2025 11:15:47 +0000

When building a url in the code, you can collect all the strings with concatenation of the form

$url = $domain.'/index.php?option='.$option.'&view='.$view.'&param1='.$value1;

and for small strings, it can even be convenient. But if there are a lot of parameters or they require standardization/cleaning in the process, then not everything is so convenient and obvious. For example, there may be a leading slash in part of the url (a slash at the beginning of the url fragment) and the incoming domain for the request may also end in a slash, and so we get an incorrect url for the request with a double slash somewhere in the middle...

For the tasks of standardization and uniformity of url retrieval, Joomla has the Joomla\Uri\Uri class. Previously, with Joomla 1.6 and older, it was called JUri. This class provides work with urls according to the RFC3986 standard and takes over the work of parsing URLs for spare parts or assembling URLs from spare parts))

Example: get a specific parameter from the url.

use Joomla\Uri\Uri;

$url = 'https://web-tolk.ru/dev/biblioteki?param=value';
$uri = new Uri($url);
// output the line 'value' here
echo $uri->getVar('param');

Yes, there is a native PHP function parse_url, you might say... But the Uri class ensures safe operation with UTF-8 in urls, including Cyrillic domains. In order not to write various checks yourself, you can use the features of the Joomla core.

How to build required url in the code in Joomla

Here, too, everything is simple:

use Joomla\Uri\Uri;

$uri = new Uri;
$uri->setHost('web-tolk.ru');
$uri->setScheme('https');
// setPath() starts with leading slash
$uri->setPath('/dev/biblioteki');
// GET-parameters can be passed as an array
$vars = [
        'param1' => 'value1',
        'param2' => 'value2',
        'param3' => 'value3',
];
$uri->setQuery($vars);
// echo our url like string
echo $uri->toString();

The hierarchy of Uri classes in Joomla is designed so that getter methods are in the AbstractUri class, and setters are in the Uri class. The setters can be viewed in the file libraries/vendor/joomla/uri/src/Uri.php . We look at Hetaera in the file libraries/vendor/joomla/uri/src/AbstractUri.php.

If you have PHPStorm, then it knows Joomla perfectly well and tells you everything you need.
Well, you can give a link to the old documentation page, which is still mostly relevant, adjusted for the use of namespaces.

Uri structure:

     foo://example.com:8042/over/there?name=ferret#nose
     \_/   \______________/\_________/ \_________/ \__/
      |           |            |            |        |
   scheme     authority       path        query   fragment

Joomla Community resources

The anatomy of smart search in Joomla 5. Creating a plugin Part 3

Sergey Tolkachyov — Fri, 03 Jan 2025 06:29:11 +0000

In the first article, we got acquainted with the capabilities of the Joomla smart search component, talked about the parameters and configuration of scheduled indexing using CRON. And in the second article we've started to code our custom plugin for Joomla smart search component. So, let's finish it!

The index() method

This method should adapt the data obtained from the database in order to submit it for indexing. As an argument, the $item element (article, product, tag, etc.) is passed to it as an instance class of the \Joomla\Component\Finder\Administrator\Indexer\Result class. The properties of $item match those that we selected from the database. The ultimate goal of this method is to call $this->indexer->index($item).

You need to understand what the search results will look like in order to understand what to compare with what.

Joomla 5 smart search result structure

Here I take the names straight from the code. In this case, the images are not shown in the search results, but they are also there - $this->result->imageUrl.

imageUrl - a picture of the Joomla article, product, tag, contact. It is displayed if enabled in the settings of the smart search component.
title - the title of the material, the name of the product, contact, etc.
description and body - a text description. We remember that many entities in Joomla have a short and complete description or an introductory and full text. Here they are combined and then trimmed to the character limit specified in the settings. body is the full text or description.
getTaxonomy() - the method receives and outputs taxonomy data for a given search result.

Thus, we have few data visible to the user - only 4 types. And we get more data from the database. We need to understand which of them will be available for indexing by search, and which will only be displayed.

Here is the code of the index() method with comments.

<?php
/**
 * Method to index an item. The item must be a Result object.
 *
 * @param   Result  $item  The item to index as a Result object.
 *
 * @return  void
 *     
 * @throws  \Exception on database error.
 * @since   2.5
 */
protected function index(Result $item)
{
    // Setting the language of the indexed element - the default language of the site
    $item->setLanguage();
    // Check if JoomShopping is enabled in Joomla.
    if (ComponentHelper::isEnabled($this->extension) === false)
    {
        return;
    }
    // We take part of the paths to the pictures from the component parameters.
    $this->loadJshopConfig();
    // Setting the context for indexing
    $item->context = 'com_jshopping.product';

    // We collect all the parameters in a bunch: the search component, JoomShopping and the site.
    // They will be available to us in the output layout
    $registry     = new Registry($item->params);
    $item->params = clone ComponentHelper::getParams('com_jshopping', true);
    $item->params->merge($registry);
    $item->params->merge((new Registry($this->jshopConfig)));
    // Meta-data: meta-keywords, meta description, author,
    // index / no-index values for robots
    $item->metadata = new Registry($item->metadata);

    // Process the content with content plugins - the onContentPrepare event.
    // Content plugins always have a context check.
    // If it is equal to 'com_finder.indexer', then content plugins will usually not work.
    // ONLY TEXT should be given for indexing.
    // Neither pictures nor YouTube videos should get there, so
    // the indexed content will be cleared of HTML tags.
    // The raw short codes are just text and can get
    // into the search results.

    $item->summary = Helper::prepareContent($item->summary, $item->params, $item);
    $item->body    = Helper::prepareContent($item->body, $item->params, $item);
    // Include here JoomShopping classed.
    require_once JPATH_SITE . '/components/com_jshopping/bootstrap.php';
    \JSFactory::loadAdminLanguageFile($this->languageTag, true);

    //
    // A trick. We want to be able to search by price, product code, etc too.
    // Attaching all this data to the body.
    //

    // Manufacturer code
    $manufacturer_code = $item->getElement('manufacturer_code');
    if (!empty($manufacturer_code))
    {
        $item->body .= ' ' . Text::_('JSHOP_MANUFACTURER_CODE') . ': ' . $manufacturer_code;
    }

    // EAN
    $product_ean = $item->getElement('product_ean');
    if (!empty($product_ean))
    {
        $item->body .= ' ' . Text::_('JSHOP_EAN') . ': ' . $product_ean;
    }

    // Old price
    $product_old_price = (float) $item->getElement('product_old_price');
    if (!empty($product_old_price))
    {
        $product_old_price = \JSHElper::formatPrice($item->getElement('product_old_price'));
        $item->body        .= ' ' . Text::_('JSHOP_OLD_PRICE') . ': ' . $product_old_price;
    }

    // Buy price
    $product_buy_price = (float) $item->getElement('product_buy_price');
    if (!empty($product_buy_price))
    {
        $product_buy_price = \JSHElper::formatPrice($item->getElement('product_buy_price'));
        $item->body        .= ' ' . Text::_('JSHOP_PRODUCT_BUY_PRICE') . ': ' . $product_buy_price;
    }
    // Price
    $product_price = (float) $item->getElement('product_price');
    if (!empty($product_price))
    {
        $product_price = \JSHElper::formatPrice($product_price);
        $item->body    .= ' ' . Text::_('JSHOP_PRODUCT_PRICE') . ': ' . $product_price;
    }


    // URL - the unique key of the element in the table. Read more about this after the sample code
    $item->url = $this->getUrl($item->slug, 'com_jshopping', $item->catslug);

    // Link to element - to JoomShopping product
    $item->route = $item->url;

    // A menu item can be created for product. Menu item has own page header.
    // Joomla menu has higher priority then we'll take data from it.
    $title = $this->getItemMenuTitle($item->url);

    // Adjust the title if necessary.
    if (!empty($title) && $this->params->get('use_menu_title', true))
    {
        $item->title = $title;
    }

    // Add product image
    $product_image = $item->getElement('image');
    if (!empty($product_image))
    {
        $item->imageUrl = $item->params->get('image_product_live_path') . '/' . $product_image;
        $item->imageAlt = $item->title;
    }

    // The product has no author. But you can do this if you search by author/user
    // For example, you enabled search by author in the smart search component settings
    // and it should search for everything related to this author
    // $item->metaauthor = $item->metadata->get('author');

    // Add the metadata processing instructions.
    $item->addInstruction(Indexer::META_CONTEXT, 'metakey');
    $item->addInstruction(Indexer::META_CONTEXT, 'metadesc');
    // $item->addInstruction(Indexer::META_COTNTEXT, 'metaauthor');
    // $item->addInstruction(Indexer::META_CONTEXT, 'author');
    // $item->addInstruction(Indexer::META_CONTEXT, 'created_by_alias');

    // Access group for the default search result.
    // We hardcode "1" - that is, for everyone. But here you can
    // take the access group from the product.
    // Or show different search results to different access groups.
    $item->access = 1;

    // Check if the category for the product is published.
    // Products should only be published if their category is published.
    $item->state = $this->translateState($item->state, $item->cat_state);

    // Get the list of taxonomies to display from the plugin parameters
    $taxonomies = $this->params->get('taxonomies', ['product', 'category', 'language']);
    // Name of the search type in the drop-down list of types: materials, contacts.
    // In our case - product. We take a language constant for this.
    $item->addTaxonomy('Type', Text::_('JSHOP_PRODUCT'));
    // Add product categories to the drop-down list
    // categories so that you can search only in a specific
    // categories. Here we already transfer the names of the categories.
    $item->addTaxonomy('Category', $item->category);
    // Search only in the desired language
    $item->addTaxonomy('Language', $this->getLangTag());
    // Search results can be limited by publication start and end dates
    $item->publish_start_date = Factory::getDate()->toSql();
    $item->start_date         = Factory::getDate()->toSql();

    // Add additional data for the indexed element.
    // Here in the helper the "onPrepareFinderContent" event is called
    // This is usually how comments, tags, labels
    // and other things that should be available for search are added.
    // Accordingly, individual plugins work with this event.
    // In our case, we do not need this yet.
    // Helper::getContentExtras($item);

    // Add custom fields (com_fields) Joomla, if the component
    // supports them.
    // In our case, we do not need this yet.
    // Helper::addCustomFields($item, 'com_jshopping.product');

    // Index the item.
    $this->indexer->index($item);
}

Types of instructions for "marking up the weight" of content for indexing.

I am not an expert in fine-tuning indexing, so I will try to describe what I could see in the code. In the parameters of the smart search component, there are weight settings for each part of the indexed content: title, main text, metadata, url, additional text.

Joomla 5 smart search params - indexing weight settings for title, body, metadata

We have already seen these settings above in the first article in seria, but for convenience we will repeat the screenshot.

In our smart search plugin, we can specify which data in our object for indexing belongs to which type by adding instructions:

<?php
// In the index() method
$item->addInstruction(Indexer::TEXT_CONTEXT, 'product_buy_price');

We look at the types of context for instructions and their names by default in the class \Joomla\Component\Finder\Administrator\Indexer\Result.

Joomla smart search indexing instructions types for weight markup

As I later found out, list_price and sale_price refer to indexing, not to the terminology of an online store.

getUrl() method

The unique key for searching is essentially the url of the element in its system form: index.php?option=com_content&view=article&id=1. In the database in the #__finder_links table, it is stored in the url column. But to build a link in the frontend to the desired element from the search results, a more complex option is used with a combination of id and aliases in the url: index.php?option=com_content&view=article&id=1:article-alias&catid=2, which is stored in the adjacent route column. But Joomla routing will determine the final url without specifying an alias, in which case the content of the url and route will be the same.

<?php
// Fragment of index() method of smart search plugin for Joomla materials

// Create a URL as identifier to recognise items again.
$item->url = $this->getUrl($item->id, $this->extension, $this->layout);

// Build the necessary route and path information.
$item->route = RouteHelper::getArticleRoute($item->slug, $item->catid, $item->language);

The system url for the indexed element looks different in different components. In the components that follow the "Joomla way", you can use one controller, which, if no specific controller is found, will immediately show the desired View. Therefore, in standard Joomla components, we usually do not find links indicating the controller in the GET parameters. They will all look like index.php?option=com_content&view=article&id=15. This is the url that the getUrl() method of the Adapter class returns to us.

<?php
/**
 * Method to get the URL for the item. The URL is how we look up the link
 * in the Finder index.
 *
 * @param   integer  $id         The id of the item.
 * @param   string   $extension  The extension the category is in.
 * @param   string   $view       The view for the URL.
 *
 * @return  string  The URL of the item.
 *
 * @since   2.5
 */
protected function getUrl($id, $extension, $view)
{
    return 'index.php?option=' . $extension . '&view=' . $view . '&id=' . $id;
}

However, JoomShopping has its own story and URLs are built somewhat differently. We will not be able to use the standard method and we are redefining it.

<?php
use Joomla\CMS\Uri\Uri;

/**
 * @param string $product_id  Product id
 * @param string $extension  Always 'com_jshopping'
 * @param string $view  Not used for JoomShopping
 *
 * @return string
 *
 * @since 1.0.0
 */
public function getUrl($product_id, $extension, $view = 'not_used') : string
{
    /**
     * There is the trick. For JoomShopping product url construction
     * we need only in product id and category id
     */
    $this->loadJshopConfig();
    // Keeping in mind the difficulties with categories in JoomShopping
    // we separate the process of getting the category into a separate method.
    $category_id = $this->getProductCategoryId((int)$product_id);
    $url = new Uri();
    $url->setPath('index.php');
    $url->setQuery([
        'option'      => 'com_jshopping',
        'controller'  => 'product',
        'task'        => 'view',
        'category_id' => $category_id,
        'product_id'  => $product_id,
    ]);
    // When constructing a url in JoomShopping, it is advisable to find and specify
    // The correct itemId is the id of the menu item for JoomShopping.
    // Otherwise, we may have duplicate pages by url
    // We connected the JoomShopping API earlier, so the JSHelper should already be here.
    $defaultItemid = \JSHelper::getDefaultItemid($url->toString());
    $url->setVar('Itemid', $defaultItemid);

    return $url->toString();
}

An atypical implementation of multilingualism. Indexation.

Let's return to the problem of multilingualism, in which we do not have a separate indexed entity for each content language. But there is an indexed entity that contains values for all languages at once.

The solution is to get a list of all languages inside the index() method, collect the Result object for each language and then give each object for indexing. We need to divide the data into those that are the same for both languages (usually catid, access, etc.) and different (title, description, fulltext etc.). That is, the $this->indexer->index() method will be called several times inside the Index() method of our plugin.

<?php
/**
 * Method to index an item. The item must be a Result object.
 *
 * @param   Result  $item  The item to index as a Result object.
 *
 * @return  void
 *
 * @throws  \Exception on database error.
 * @since   2.5
 */
protected function index(Result $item)
{

    // Initialise the item parameters.
    $registry     = new Registry($item->params);
    $item->params = clone ComponentHelper::getParams('com_swjprojects', true);
    $item->params->merge($registry);
    $item->context = 'com_swjprojects.project';
    $lang_codes    = LanguageHelper::getLanguages('lang_code');

    $translates = $this->getTranslateProjects($item->id, $item->catid);

    // Translate the state. projects should only be published if the category is published.
    $item->state = $this->translateState($item->state, $item->cat_state);

    // Get taxonomies to display
    $taxonomies = $this->params->get('taxonomies', ['type', 'category', 'language']);

    // Add the type taxonomy data.
    if (\in_array('type', $taxonomies))
    {
        $item->addTaxonomy('Type', 'Project');
    }

    $item->access = 1;
    foreach ($translates as $translate)
    {
        $item->language = $translate->language;
        $item->title    = $translate->title;
        // Trigger the onContentPrepare event.
        $item->summary = Helper::prepareContent($translate->introtext, $item->params, $item);
        $item->body    = Helper::prepareContent($translate->fulltext, $item->params, $item);

        $metadata       = new Registry($translate->metadata);
        $item->metakey  = $metadata->get('keywords', '');
        $item->metadesc = $metadata->get('description', $translate->introtext);
        // Add the metadata processing instructions.
        $item->addInstruction(Indexer::META_CONTEXT, 'metakey');
        $item->addInstruction(Indexer::META_CONTEXT, 'metadesc');

        $lang = '';

        if (Multilanguage::isEnabled())
        {
            foreach ($lang_codes as $lang_code)
            {
                if ($translate->language == $lang_code->lang_code)
                {
                    $lang = $lang_code->sef;
                }
            }
        }
        // Create a URL as identifier to recognise items again.
        $item->url = $this->getUrl($item->id, $this->extension, $this->layout, $lang);

        // Build the necessary route and path information.
        $item->route = RouteHelper::getProjectRoute($item->id, $item->catid);

        // Get the menu title if it exists.
        $title = $this->getItemMenuTitle($item->route);

        // Adjust the title if necessary.
        if (!empty($title) && $this->params->get('use_menu_title', true))
        {
            $item->title = $title;
        }

        // Add the category taxonomy data.
        if (\in_array('category', $taxonomies))
        {
            $item->addTaxonomy('Category', $translate->category, 1, 1, $item->language);
        }

        // Add the language taxonomy data.
        if (\in_array('language', $taxonomies))
        {
            $item->addTaxonomy('Language', $item->language, 1, 1, $item->language);
        }


        $item->metadata = new Registry($item->metadata);

        $icon = ImagesHelper::getImage('projects', $item->id, 'icon', $item->language);

        // Add the image.
        if (!empty($icon))
        {
            $item->imageUrl = $icon;
            $item->imageAlt = $item->title;
        }

        // Add the meta author.
        // $item->metaauthor = $item->metadata->get('author');

        // Get content extras.
        // Helper::getContentExtras($item);
        // Helper::addCustomFields($item, 'com_swjprojects.project');

        // Index the item.
        $this->indexer->index($item);
    }
}

We also need to unify the value for the route field for each language, so we make our own implementation of the getUrl() method and add the $lang parameter to the url.

<?php
/**
 * @param   int     $id
 * @param   string  $extension
 * @param   string  $view
 * @param   string  $lang  Language SEF code like `ru`, `en` etc
 *
 * @return string
 *
 * @since 2.1.0
 */
public function getUrl($id, $extension, $view, $lang = '')
{
    $url = 'index.php?option=' . $extension . '&view=' . $view . '&id=' . $id;

    if (!empty($lang))
    {
        $url .= '&lang=' . $lang;
    }

    return $url;
}

getItems() and getContentCount() methods

In general, we don't need anything else for manual indexing and reindexing of content, as well as scheduled via the CLI. However, if we come across some very unusual beast in the form of non-Joomla data, some third-party database, then we can completely redefine the logic of the parent Adapter class for these purposes.

getContentCount() - the method should return an integer - the number of indexed elements.
getItems($offset, $limit, $query = null) - under the hood, calls getListQuery() and sets $offset and $limit, brings everything to a single view - objects.

If using one getListQuery() method and accessing it from 3 other methods is inconvenient for some reason, you can customize requests and their processing in redefined methods.

Reindexing content on the fly

To solve this problem, we have several ways, two of which are the periodic manual and CRON indexing, as I wrote above. However, this is fraught with an untimely index update and site users may not receive updated data in search results on time. Therefore, there is another way: reindexing the content on the fly, immediately after saving the changes. To do this, a content group plugin is created, which triggers smart search plugin events at the right moments.

Content plugin for joomla smart search

Standard Joomla Model Events.
If the component is written according to the canons of Joomla and inherits its classes, then many models (Model - MVC) trigger standard events, among which we are interested in several:
onContentBeforeSave - The event is triggered before any Joomla entity is saved.

onContentAfterSave - The event is triggered after saving any Joomla entity.
onContentAfterDelete - The event is triggered after deleting any Joomla entity.
onContentChangeState - the event is triggered after a state change (unpublished/published).
onCategoryChangeState - The event is triggered after the category status changes (if the standard Joomla categories component is used).

By default, the smart search plugin causes the content to be reindexed at the listed points in time. In each of these events, the context of the event call is passed in the form of <component>.<entity>, for example, com_content.article or com_menus.menu. According to the desired context, you can determine whether to start reindexing or not. We are already doing this check in the smart search plugin. An example from the code of the Finder content plugin for Joomla articles:

<?php
use Joomla\CMS\Event\Finder as FinderEvent;

/**
 * Smart Search after save content method.
 * Content is passed by reference, but after the save, so no changes will be saved.
 * Method is called right after the content is saved.
 *
 * @param   string  $context  The context of the content passed to the plugin (added in 1.6)
 * @param   object  $article  A \Joomla\CMS\Table\Table\ object
 * @param   bool    $isNew    If the content has just been created
 *
 * @return  void
 *
 * @since   2.5
 */
public function onContentAfterSave($context, $article, $isNew): void
{
    $this->importFinderPlugins();

    // Trigger the onFinderAfterSave event.
    $this->getDispatcher()->dispatch('onFinderAfterSave', new FinderEvent\AfterSaveEvent('onFinderAfterSave', [
        'context' => $context,
        'subject' => $article,
        'isNew'   => $isNew,
    ]));
}

As we can see, the onFinderAfterSave event is called here, which is specific specifically for smart search plugins. And in the onFinderAfterSave() method of our smart search plugin, there is already a check for the desired context and reindexing.

<?php
use Joomla\CMS\Event\Finder as FinderEvent;

/**
 * Smart Search after save content method.
 * Reindexes the link information for an article that has been saved.
 * It also makes adjustments if the access level of an item or the
 * category to which it belongs has changed.
 *
 * @param   FinderEvent\AfterSaveEvent   $event  The event instance.
 *
 * @return  void
 *
 * @since   2.5
 * @throws  \Exception on database error.
 */
public function onFinderAfterSave(FinderEvent\AfterSaveEvent $event): void
{
    $context = $event->getContext();
    $row     = $event->getItem();
    $isNew   = $event->getIsNew();

    // We only want to handle articles here.
    if ($context === 'com_content.article' || $context === 'com_content.form') {
        // Check if the access levels are different.
        if (!$isNew && $this->old_access != $row->access) {
            // Process the change.
            $this->itemAccessChange($row);
        }

        // Reindex the item.
        $this->reindex($row->id);
    }

    // Check for access changes in the category.
    if ($context === 'com_categories.category') {
        // Check if the access levels are different.
        if (!$isNew && $this->old_cataccess != $row->access) {
            $this->categoryAccessChange($row);
        }
    }
}

In the same way, the work is organized when the state changes and the article or product is deleted.

getItem() method

This method gets the indexed element by its id. It is called when reindexing after saving articles, products, etc. - on the onFinderAfterSave event. Internally, it receives an SQL query from the getListQuery() method, adds the id of the requested entity to it, and executes the query. However, in the parent class, the id field with the prefix a is hardcoded for tables - $query->where('a.id = ' . (int) $id). Since in our case both the prefix and the name of the field for the request are different, we redefine the method too.

<?php
// I have indicated here only the namespaces used in the example
use Joomla\Utilities\ArrayHelper;
use Joomla\Component\Finder\Administrator\Indexer\Result;

/**
 * Method to get a content item to index.
 *
 * @param   integer  $id  The id of the content item.
 *
 * @return  Result  A Result object.
 *
 * @throws  \Exception on database error.
 * @since   2.5
 */
protected function getItem($id)
{
    // Get the list query and add the extra WHERE clause.
    $query = $this->getListQuery();
    $query->where('prod.product_id = ' . (int) $id);

    // Get the item to index.
    $this->db->setQuery($query);
    $item = $this->db->loadAssoc();

    // Convert the item to a result object.
    $item = ArrayHelper::toObject((array) $item, Result::class);

    // Set the item type.
    $item->type_id = $this->type_id;

    // Set the item layout.
    $item->layout = $this->layout;

    return $item;
}

Conclusion

This articles seria does not pretend to be a complete description of the mechanics of smart search in Joomla, even after 4 months of work on it. And in this case it is not a metaphor. But I hope this article will help those who will take up writing plugins for indexing data from Joomla components or third-party systems.

I will gratefully accept suggestions for improving the article and additions in the comments.

Joomla Community resources

https://joomla.org/
This article in Joomla Community Magazine
Joomla Community chat in Mattermost (read more)

Connecting third-party PHP libraries in Joomla

Sergey Tolkachyov — Fri, 27 Dec 2024 07:23:03 +0000

PHP libraries are convenient because they can be accessed from anywhere in the Application: from a plugin, component model, module, etc. If someone has already solved a similar problem and designed it as a library (and even updates it), it makes sense to connect this library to your Joomla. For example, to develop a payment method for an online store, you need the official library of a payment aggregator. Or are you satisfied with the official PHP SDK of some CRM.

Composer

Joomla does not support working with Composer directly. In order to use the library in your work, you need to "wrap" it in a Joomla extension type library and install it. In serious projects, the approach of fixing versions of all components of the project is adopted: the code has been checked more than once, tested and allowed to work in the production.

You create a package with your library, install it wherever you need it. As new versions of the library are released, you update your wrapper and get all the advantages of working with Joomla extensions: updating extensions in the standard way, including through the CLI. View the Changelog of the extension in the admin area BEFORE updating, etc.

View the Changelog extension in the admin area BEFORE updating to Joomla 5.

Joomla, PSR, Symfony

Joomla complies with PSR standards, so it is convenient to work with it in this regard. Some Symfony packages are included in the Joomla core (console, string, vardumper, yaml, error-handler and others), so if you suddenly want to add more, they will fit in and work well. You can see what else is worth in Joomla besides Symfony components in libraries/vendor.

How to wrap a 3rd-party PHP library in a Joomla extension?

Nothing complicated. The library files are usually located in the src folder. Next to this folder, you need to create an XML manifest of the Joomla extension according to the documentation (manual.joomla.org). Then we pack everything into a zip archive and that's it! It can be installed.

If you need your own tables in the database for the library to work, you need to add the necessary files with SQL queries during installation or update. Since Joomla 4+ works with namespaces, it is important to specify this namespace in the XML manifest for the extension. Here is an abbreviated example of an XML manifest for the Joomla library.

<?xml version="1.0" encoding="UTF-8" ?>
<extension type="library" method="upgrade">
     <name>WebTolk AmoCRM library</name>
     <libraryname>Webtolk/Amocrm</libraryname>
     <version>1.2.1</version>
     ...
     <namespace path="src">Webtolk\Amocrm</namespace>
     <files>
          <folder>src</folder>
          <filename>amocrm.xml</filename>
     </files>
</extension>

The <libraryname> tag means that the src folder from our archive will be copied to JPATH_SITE/libraries/Webtolk/Amocrm. In the <files> section, we indicate what needs to be filled in from the archive. And <namespace path="src">Webtolk\Amocrm</namespace> says that the namespace Webtolk\Amocrm must be registered for the src folder in JPATH_SITE/libraries/Webtolk/Amocrm.

Important notes!

Before Joomla 4.2.7, in fact, the tag <namespace> from the XML manifest did not work. Therefore, it was necessary to add a system plugin to the library package that would register the namespace on the onAfterInitialize event (Event Dispatcher) using JLoader class. Accordingly, it was necessary to build a package from the library and the plugin. Starting with Joomla 4.2.7, it has been fixed and you can do without the plugin.
So far, updating the library = reinstalling. That is, the extension is removed and installed. This decision was made somewhere in the depths of the versions of Joomla 3.x. Why? - hidden under the mountains of PR. We need to search. Why is this important? Because when installing any extension, an entry is created in the "registry" of extensions - in the database in the #__extensions table. This table has 2 columns of type TEXT - params and custom_data. And this, you must admit, is a considerable amount of data. If you store some library parameters in a database using Joomla\CMS\Helper\LibraryHelper, then you need to take this behavior of the installer into account and pre-save and then add the saved parameters back to the extension's installer script when updating the library.

<?php
use Joomla\CMS\Helper\LibraryHelper;
use Joomla\CMS\Cache\Cache;

/**
 * Function called before extension installation/update/removal procedure commences.
 *
 * @param   string            $type     The type of change (install or discover_install, update, uninstall)
 * @param   InstallerAdapter  $adapter  The adapter calling this method
 *
 * @return  boolean  True on success
 *
 * @since   1.0.0
 */
public function preflight(string $type, InstallerAdapter $adapter): bool
{
    if ($type == 'uninstall')
    {
        return true;
    }

    /**
     *
     *  Joomla when updating extensions of the library type, it actually deletes them (along with the data in the database),
     *  and then installs it again.
     *  In order to avoid losing library data from the database, we are writing this crutch.
     *
     * @see https://github.com/joomla/joomla-cms/issues/39360
     *
     */

    if ($type == 'update')
    {
        $lib_params = LibraryHelper::getParams('Webtolk/Amocrm');
        $jconfig    = $this->app->getConfig();
        $options    = array(
            'defaultgroup' => 'wt_amo_crm_temp',
            'caching'      => true,
            'cachebase'    => $jconfig->get('cache_path'),
            'storage'      => $jconfig->get('cache_handler'),
        );
        $cache      = Cache::getInstance('', $options);
        $cache->store($lib_params, 'wt_amo_crm_temp');

    }

    return true;

}

And in the postflight() method accordingly, we put the saved parameters back using LibraryHelper::saveParams('Webtolk/Amocrm', $lib_params);.

For the library to work, it must be enabled in the extension manager (Menu - System - Management - Extensions).
Often, certain parameters (API keys, tokens, etc.) are needed for the library to work, which must be specified by people in the Joomla admin area. For these purposes, it is convenient to write a plugin (an extension type library does not have its own interface for configuring parameters). Either the system one or your own custom group doesn't matter. Inside your library, you can get plugin parameters pretty quickly like this:

<?php
use Joomla\CMS\Plugin\PluginHelper;
use Joomla\Registry\Registry;

if (PluginHelper::isEnabled('system', 'wt_amocrm'))
   {
      $plugin        = PluginHelper::getPlugin('system', 'wt_amocrm');
      $params        = \json_decode($plugin->params);
      $param = $params->param;
      // OR you can use Joomla\Registry\Registry
      $params = new Registry($plugin->params);
      $param = $params->get('param', 'defatul value if empty');
   }

DEV Community: Sergey Tolkachyov

Process Forge: a framework for creating AI processes

Starting Points

Process Forge Concepts

Process Instead of Chat

Connecting Knowledge to an AI Process

Connecting Tools, MCP, and Templates

Templates

Tools and MCP

Processes Again

Platforms and Specialisations

Platforms

Specialisations

Cascading Project Context Computation

The General Feedback Mechanism: Evolve

Versioning

Organising Work in Process Forge

Garage Mode (1-1-1-1)

Forge / Factory Mode

Conclusion

How to work with the component menu in the Joomla admin panel using preset.xml and the plugin.

CFI Plugin v.2.0.0 Released - Export/Import Joomla Articles to/from CSV

v.2.0.0. What's New?

Joomla View Logs component v.2.3.0 has been released!

v.2.3.0 What's new?

Joomla-дайджест. 2-е полугодие 2025 года.

WT IndexNow - send your Joomla urls to search engines via IndexNow protocol

Supported components

Links

WT Yandex map items v.2.0.5 Joomla module has been released

v.2.0.5. What's new?

UX improving

Joomla 5.2.4 Security & Bugfix Release

Security Fix

Bug fixes and Improvements with 5.2.4

Joomla Community resources

Joomla tip: show notifications by Joomla.renderMessages

Rendering of Joomla messages in the frontend

Joomla Community resources

Joomla tip: Use the Joomla\Uri\Uri class to create a URL.

Example: get a specific parameter from the url.

How to build required url in the code in Joomla

Joomla Community resources

The anatomy of smart search in Joomla 5. Creating a plugin Part 3

The index() method

Types of instructions for "marking up the weight" of content for indexing.

getUrl() method

An atypical implementation of multilingualism. Indexation.

getItems() and getContentCount() methods

Reindexing content on the fly

getItem() method

Conclusion

Joomla Community resources

Connecting third-party PHP libraries in Joomla

Composer

Joomla, PSR, Symfony

How to wrap a 3rd-party PHP library in a Joomla extension?

Important notes!

Joomla Community resources