Leafiny Documentation
Objects
There are 6 types of objects in Leafiny:
- Page: a page renders a template
- Block: a block is a unit of page output that renders some distinctive content
- Mail: a mail renders a template to send by e-mail
- Helper: a helper contains usefull methods that can be use anywhere
- Observer: an observer is called when an event is dispatched
- Model: a model provides access to the database
Generalities
All objects extend the Leafiny_Object class. This class allows you to add, modify or delete data on the object.
$helper = new Leafiny_Helper();
$helper->setData('welcome', 'Hello!');
// OR
$helper->setWelcome('Hello!');
echo $helper->getData('welcome');
// OR
echo $helper->getWelcome();
Object factory
An object must be declared in the module config file as follow:
/** modules/Vendor_Example/etc/config.php **/
'helper' => [ // Object type
'my_helper' => [ // Object identifier
'class' => Example_Helper_Data::class, // Object class
'welcome' => 'Hello %s!' // Custom variable
],
],
Here, the Example_Helper_Data class contains one method that displays a welcome message:
<?php
/** modules/Vendor_Example/app/Example/Helper/Data.php **/
declare(strict_types=1);
class Example_Helper_Data extends Core_Helper
{
/**
* Welcome Message
*
* @param string $name
*
* @return string
*/
public function getWelcomeMessage(string $name): string
{
$welcome = $this->getCustom('welcome');
return sprintf($welcome, $name);
}
}
Anywhere, this helper must be instancied with App::getObject($type, $identifier) or App::getSingleton($type, $identifier) methods:
$helper = App::getObject('helper', 'my_helper');
// OR
$helper = App::getSingleton('helper', 'my_helper');
In most cases it is better to use the singleton.
The object factory assigns to the object all custom variables defined in the configuration file for the my_helper identifier. Then these variables are accessible with the getCustom method.
This system allows a customization of the variables simply by overloading the value in a configuration file (Frontend or custom module). See How config variables work.
Page
Add a new page
/** modules/Vendor_Example/etc/config.php **/
'page' => [
'/example.html' => [
'title' => 'Example Page',
'content' => 'Vendor_Example::page/hello.twig',
'meta_title' => 'Example',
'meta_description' => 'This is an example page',
'class' => Example_Page_Hello::class,
],
],
Note: if the class key is missing, the default class will be Core_Page.
Page content
<!-- modules/Vendor_Example/template/page/hello.twig -->
<p>Hello World!</p>
<p>5 + 9 = {{ page.add(5, 9) }}</p>
Page class
<?php
/** modules/Vendor_Example/app/Example/Page/Hello.php **/
declare(strict_types=1);
/**
* Class Example_Page_Hello
*/
class Example_Page_Hello extends Core_Page
{
/**
* Execute action
*
* @return void
*/
public function action(): void
{
parent::action();
// Custom logic
}
/**
* Add 2 integers
*
* @return int
*/
public function add(int $a, int $b): int
{
return $a + $b;
}
}
See Routes section for more information.
Block
Add a new block
/** modules/Vendor_Example/etc/config.php **/
'block' => [
'my.block.name' => [
'template' => 'Vendor_Example::block/hello.twig',
'class' => Example_Block_Hello::class
],
],
Note: if the class key is missing, the default class will be Core_Block.
Block content
<!-- modules/Vendor_Example/template/block/hello.twig -->
<p>Hello {{ block.getName }}!</p>
Block class
<?php
/** modules/Vendor_Example/app/Example/Block/Hello.php **/
declare(strict_types=1);
/**
* Class Example_Block_Hello
*/
class Example_Block_Hello extends Core_Block
{
/**
* Retrieve the name
*
* @return string
*/
public function getName(): string
{
return 'Leafiny';
}
}
Display the block
<!-- modules/Vendor_Example/template/page/hello.twig -->
{{ child('my.block.name') }}
Add a new mail
/** modules/Vendor_Example/etc/config.php **/
'mail' => [
'mail.example' => [
'subject' => 'Hello World!',
'template' => 'Vendor_Example::mail/hello.twig',
'class' => Example_Mail_Hello::class
]
],
Note: if the class key is missing, the default class will be Core_Mail.
Mail content
<!-- modules/Vendor_Example/template/mail/hello.twig -->
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="{{ mail.getLanguage }}" xml:lang="{{ mail.getLanguage }}">
<head>
<meta http-equiv="Content-Type" content="text/html; charset={{ mail.getCharset }}">
<title>{{ mail.getSubject|translate }}</title>
</head>
<body>
<p>Hello {{ mail.getCustomer.getName }}!</p>
<p>Today is {{ mail.getDate }}</p>
</body>
</html>
Mail class
<?php
/** modules/Vendor_Example/app/Example/Mail/Hello.php **/
declare(strict_types=1);
/**
* Class Example_Mail_Hello
*/
class Example_Mail_Hello extends Core_Mail
{
/**
* Retrieve the current date
*
* @return string
*/
public function getDate(): string
{
return strftime('%d %b %Y %H:%M:%S');
}
}
Send the mail
/** @var Core_Mail $mail */
$mail = App::getObject('mail', 'mail.example');
$mail->setRecipientEmail('contact@example.com');
$customer = new Leafiny_Object();
$customer->setData(
[
'name' => 'Leafiny',
]
);
$mail->send(['customer' => $customer]);
Helper
Add a new helper
/** modules/Vendor_Example/etc/config.php **/
'helper' => [
'my_helper' => [
'class' => Example_Helper_Data::class,
'welcome' => 'Hello %s!',
],
],
Note: if the class key is missing, the default class will be Core_Helper.
Helper class
<?php
/** modules/Vendor_Example/app/Example/Helper/Data.php **/
declare(strict_types=1);
/**
* Class Example_Helper_Data
*/
class Example_Helper_Data extends Core_Helper
{
/**
* Welcome Message
*
* @param string $name
*
* @return string
*/
public function getWelcomeMessage(string $name): string
{
$welcome = $this->getCustom('welcome');
return sprintf($welcome, $name);
}
}
Use helper
In any class:
/** @var Example_Helper_Data $helper **/
$helper = App::getSingleton('helper', 'my_helper');
$message = $helper->getWelcomeMessage('John Doe');
In page template:
{{ page.getHelper('my_helper').getWelcomeMessage('John Doe') }}
Observer
Add a new observer
/** modules/Vendor_Example/etc/config.php **/
'events' => [
'page_render_before' => [ // Dispatched event name to observe
'observer_example' => 100, // Custom and unique observer name with sort order as value
],
],
'observer' => [
'observer_example' => [ // The observer name
'class' => Example_Observer_Christmas::class, // The observer class name
],
],
Observer class
<?php
/** modules/Vendor_Example/app/Example/Observer/Christmas.php **/
declare(strict_types=1);
/**
* Class Example_Observer_Christmas
*/
class Example_Observer_Christmas extends Core_Observer implements Core_Interface_Observer
{
/**
* Execute
*
* @param Leafiny_Object $object
*
* @return void
* @throws Exception
*/
public function execute(Leafiny_Object $object): void
{
/** @var Core_Page $page */
$page = $object->getData('object');
if (date('md') === '1225') {
/* modules/Vendor_Example/template/christmas.twig */
$page->setCustom('template', 'Vendor_Example::christmas.twig');
}
}
}
Model
Add a new model
/** modules/Vendor_Example/etc/config.php **/
'model' => [
'document' => [
'class' => Example_Model_Document::class,
],
],
Note: if the class key is missing, the default class will be Core_Model.
Model class
<?php
/** modules/Vendor_Example/app/Example/Model/Document.php **/
declare(strict_types=1);
/**
* Class Example_Model_Document
*/
class Example_Model_Document extends Core_Model
{
/**
* Main Table
*
* @var string $mainTable
*/
protected $mainTable = 'vendor_example_document';
/**
* Primary key
*
* @var string $primaryKey
*/
protected $primaryKey = 'document_id';
}
Use Model
/** @var Example_Model_Document $model **/
$model = App::getSingleton('model', 'document');
$documents = $model->getList();