Components

Components in Osumi Framework are small, reusable pieces of code that render a template. A component is composed of:

• A PHP class extending OComponent.
• A template file (php/html/json/xml depending on usage).

A component instance is created, properties are assigned, and then the component is rendered, usually via render() or by casting the object to a string.

Basic component structure

Component Class

Example of a component class file (LostPasswordComponent.php):

<?php declare(strict_types=1);

namespace Osumi\OsumiFramework\App\Component\Email\LostPassword;

use Osumi\OsumiFramework\Core\OComponent;

class LostPasswordComponent extends OComponent {
  /**
   * Public properties are automatically exposed to the template.
   */
  public ?string $token = null;
}

Template File

Example of a template (LostPasswordTemplate.php):

<div>
  Token: {{ token }}
</div>

Advanced Features

Automatic Content-Type Headers

When a component is used as a main action for a URL, the framework automatically sends the appropriate Content-Type header based on the template's file extension:

• .json: Sends Content-type: application/json.
• .xml: Sends Content-type: application/xml.
• .html / .php: Sends Content-type: text/html.

Component Nesting

Components can be chained or nested. A larger component can include and render smaller components within its logic or template to promote reusability.

Example of a child component class file (ChildComponent.php):

<?php declare(strict_types=1);

namespace Osumi\OsumiFramework\App\Component\Child;

use Osumi\OsumiFramework\Core\OComponent;

class ChildComponent extends OComponent {
  public ?string $name = null;
}

Template File

Example of a template (ChildTemplate.php):

<div>
  Name: {{ name }}
</div>

Example of a father component class file using a child component (FatherComponent.php):

<?php declare(strict_types=1);

namespace Osumi\OsumiFramework\App\Component\Father;

use Osumi\OsumiFramework\Core\OComponent;
use Osumi\OsumiFramework\App\Component\Child\ChildComponent;

class FatherComponent extends OComponent {
  public ?ChildComponent $child = null;

  public function run(): void {
    $this->child = new ChildComponent();
    $this->child->name = 'Child Name';
  }
}

Template File

Example of a template (FatherTemplate.php):

<div>
  Child: {{ child }}
</div>

The resulting output would be:

  Child: Name: Child Name

Template Syntax and Access

Templates access the component's public properties differently depending on the file extension:

1. PHP Templates (.php):

• Can execute native PHP code.
• Access public properties as standard variables (e.g., $token).

2. Static/Structured Templates (.html, .json, .xml):

• Use the double curly brace notation to output public properties: {{ variable_name }}.

The run() method (Optional)

A component can define an optional run() method. If present, it is executed automatically at the beginning of the render() process to prepare data before the template is processed.

When the component is used as an action (a component rendered as a result of an activated route), the run() function can receive requests data:

• If the run() function has a DTO, data from the request will be used to populate its fields.
• Otherwise a generic ORequest object will be passed to it.

ORequest class has methods to get data passed such as form values or parameters passed via the URL:

• getParamString('name'): returns the value of the field 'name' passed to the route as a string (null if not present).
• getParamInt('name'): returns the value of the field 'name' passed to the route as an integer (null if not present).
• getParamFloat('name'): returns the value of the field 'name' passed to the route as a float (null if not present).
• getParamBool('name'): returns the value of the field 'name' passed to the route as a boolean (null if not present).

If a route has a filter defined, the ORequest class also provides ways to access the result of their execution:

  public function run(ORequest $req): void {
    $login_filter = $req->getFilter('login'); // Would access the returned result from the LoginFilter file
    $filters = $req->getFilters(); // Would access the returned result of every applied filter as an associative array ['login' => [...]]
  }

Example:

class BooksComponent extends OComponent {
  public array $books = [];

  public function run(): void {
    $this->books = ['Book A', 'Book B'];
  }
}

class GetBookComponent extends OComponent {
  public ?Book $book = null;

  public function run(ORequest $req): void {
    $id_book = $req->getParamInt('id');
    $this->book = Book::findOne(['id' => $id_book]);
  }
}

Accessing global options

Components have methods to access to global options such as application configuration, logs or session data:

• getConfig(): Returns global OConfig to read paths or user defined values (secrets, email addresses...)
  • Docs: docs/en/concepts/config.md
• getLog(): Returns OLog instance for the component. User can log information using methods as debug, info or error.
  • Docs: docs/en/concepts/log.md
• getSession(): Returns OSession instance that can be used to access $_SESSION params.

Naming Conventions

To maintain consistency, follow these naming patterns:

Rendering Components

A typical rendering flow involves instantiating the component, assigning data, and outputting the result.

$cmp = new BooksComponent();

// You can cast it to string to trigger run() and render()
echo strval($cmp);

Template Pipes

Osumi Framework templates support Angular‑style pipes, allowing you to transform values directly inside the template.

Syntax

{{ value | pipeName }}
{{ value | pipeName:param }}
{{ value | pipeName:param1:param2 }}

Purpose

Pipes allow formatting of:

• Dates
• Numbers
• Strings
• Booleans

Pipes are processed by the internal OPipeFunctions class.

Available Pipes

Below are all built‑in pipes and their behavior, derived from the functions in OPipeFunctions.php.

1. date

Formats a date string (Y-m-d H:i:s format) into a new format.

Syntax

{{ user.created_at | date }}
{{ user.created_at | date:"d/m/Y" }}
{{ user.created_at | date:"d-m-Y H:i" }}

Behavior

• Input must be Y-m-d H:i:s
• Output is formatted using PHP DateTime::format()
• If the date is invalid → "null"

Default format

d/m/Y H:i:s

2. number

Formats numbers using PHP’s number_format().

Syntax

{{ price | number }}
{{ price | number:2 }}
{{ price | number:2:".":"," }}

Behavior

• Default decimals: 2
• Default decimal separator: "."
• Default thousand separator: ""
• If value is null → "null"

Examples:

1234.5 → 1234.50
1234.5 → 1,234.50  (if thousand separator is ",")

3. string

Applies urlencode() to a string.

Syntax

{{ user.name | string }}

Behavior

• Null → "null"
• Value → "urlencoded string"

Example:

"John Doe" → "John+Doe"

4. bool

Converts booleans to:

true
false
null

Syntax

{{ user.isAdmin | bool }}

How Pipes Behave in JSON Templates

Since templates like .json are rendered as strings, pipes automatically ensure:

• Strings are quoted when needed
• Booleans appear without quotes
• Numbers appear unquoted
• Null values appear as null

This guarantees valid JSON output.

Examples

{
  "id": {{ user.id | number }},
  "name": {{ user.name | string }},
  "created": {{ user.created_at | date:"d/m/Y" }},
  "active": {{ user.active | bool }}
}

Summary of Pipes

Model-bound Components

When components represent model views, you can use typed properties with your model classes.

namespace Osumi\OsumiFramework\App\Component\Model\User;

use Osumi\OsumiFramework\Core\OComponent;
use Osumi\OsumiFramework\App\Model\User;

class UserComponent extends OComponent {
  public ?User $user = null;
}

Best Practices

• Keep templates simple: Limit them to minimal display logic.
• Use run(): Use it for preparing data or performing calculations before rendering.
• Typed properties: Use typed public properties for clarity.
• Default values: Prefer ?type = null defaults to avoid "uninitialized property" errors in PHP 8.3+.