You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[Simple Template Engine](http://github.com/ericsizemore/simple_tpl/) is a small, simple text-based template parsing engine that works on text replacement.
16
15
17
-
> [!IMPORTANT]
18
-
> The `master` branch currently holds the work in progress version `3.x`, which is a break from the backward compatibility promise. This will be resolved once 3.0.0 is released.
19
-
> Since `3.x` is under development, it is not recommended to use in a production environment. The public api, implementations, etc. can (and will likely) change.
16
+
[Simple Template Engine](http://github.com/ericsizemore/simple_tpl/) is a small, simple text-based template parsing engine that works on text replacement.
20
17
21
18
> [!IMPORTANT]
22
-
> The `3.x` branch is mostly an introduction of caching templates. As this is in development, I'm playing around with a few different ideas. For example, right now it just caches
23
-
> the entire template after it has been parsed (so it caches template + content). This can and will likely change as I continue testing out different approaches.
19
+
> The `master` branch currently holds the work-in-progress version `3.x`, which is a break from the backward compatibility promise.
20
+
> This will be resolved once `3.0.0` is released. Since `3.x` is under development, it is not recommended to use in a production environment.
21
+
> The public API, implementations, etc., can (and will likely) change.
24
22
25
23
---
26
24
@@ -29,30 +27,111 @@
29
27
Compatible with PHP >= 8.2 and can be installed with [Composer](https://getcomposer.org).
30
28
31
29
```bash
32
-
$ composer require esi/simple_tpl
30
+
$ composer require esi/simple_tpl:^3.0
33
31
```
34
32
35
-
### Usage
33
+
## Usage
34
+
35
+
### Storage
36
+
37
+
There are two storage implementations available: `Storage\FilesystemStorage` and `Storage\DatabaseStorage`.
38
+
Both storage implementations implement the `Storage\StorageInterface` interface, with only one defined method: `loadTemplate()`.
39
+
40
+
**NOTE:** If you wish to have a system for deleting or updating the templates themselves, you would need to implement this on your own.
41
+
This library only searches for templates that have already been created, by name, then parses them with a `key => value` associative array of variables.
42
+
43
+
#### Filesystem Storage
44
+
45
+
The `FilesystemStorage` implementation allows you to use regular files for your templates.
46
+
Your template files are expected to end with the `.tpl` extension. I plan to allow the ability to use different extensions later.
36
47
37
-
Basic usage, without providing a cache library:
48
+
1. Create a `FilesystemStorage` instance with the path/directory to where your templates are located.
49
+
2. Pass this instance to the `Template` class when creating it.
38
50
51
+
Let's say you had a template called `example_template.tpl` within the `./templates/` directory.
$templateStorage = new FilesystemStorage('./templates/');
73
+
$template = new Template($templateStorage);
43
74
44
-
$tpl->setTplVars([
45
-
'title' => 'Simple Template Engine Test',
46
-
'content' => 'This is a test of the Simple Template Engine class by Eric Sizemore.',
75
+
$template->setTplVars([
76
+
'title' => 'Hello, World!',
77
+
'content' => 'This is a simple template engine.'
47
78
]);
48
79
49
-
// Parse the template file
50
-
$tpl->display(__DIR__ . '/some_template.tpl');
80
+
echo $template->parse('example_template');
51
81
```
52
82
83
+
When calling `display()` or `parse()`, you only need to provide the file name without extension.
84
+
For example, if your template file is `mytemplate.tpl`, you would call either of these methods with `mytemplate`.
85
+
86
+
#### Database Storage
87
+
88
+
The `DatabaseStorage` implementation allows you to use a database for your templates.
89
+
90
+
1. Create a `PDO` instance with your database details to create a connection.
91
+
2. Create a `DatabaseStorage` instance and pass the `PDO` instance to it.
92
+
3. Pass the `DatabaseStorage` instance to the `Template` class when creating it.
93
+
94
+
Let's say the content of the `example_template` is the same as in the [filesystem example](#filesystem-storage):
95
+
96
+
```php
97
+
use Esi\SimpleTpl\Template;
98
+
use Esi\SimpleTpl\Storage\DatabaseTemplateStorage;
99
+
use PDO;
100
+
101
+
$pdo = new PDO('mysql:host=localhost;dbname=templates', 'user', 'password');
102
+
$templateStorage = new DatabaseTemplateStorage($pdo);
103
+
$template = new Template($templateStorage);
104
+
105
+
$template->setTplVars([
106
+
'title' => 'Hello, World!',
107
+
'content' => 'This is a simple template engine.'
108
+
]);
109
+
110
+
echo $template->parse('example_template');
111
+
```
112
+
113
+
`DatabaseStorage` does not allow specifying custom table or field/column names. It expects a table named `templates` with, at minimum, two columns
114
+
named `name` (for the template name) and `content` (for the template content). I plan to allow the ability to use custom table and field/column names later.
115
+
116
+
An example on how this table may be structured:
117
+
118
+
```sql
119
+
CREATETABLEIF NOT EXISTS `templates` (
120
+
`id`INT UNSIGNED NOT NULL AUTO_INCREMENT,
121
+
`name`VARCHAR(255) NOT NULL,
122
+
`content` MEDIUMTEXT NOT NULL,
123
+
PRIMARY KEY (`id`),
124
+
UNIQUE KEY `name` (`name`)
125
+
)
126
+
```
127
+
128
+
### Caching
129
+
53
130
If you would like to utilize caching for templates, you will need to provide the library a [PSR-6](https://www.php-fig.org/psr/psr-6/) cache implementation.
54
131
You can view a list of packages that provide this implementation on [Packagist](https://packagist.org/providers/psr/cache-implementation).
55
132
133
+
Whether you use `FilesystemStorage` or `DatabaseStorage`, you can use caching for either by passing an object that implements `\Psr\Cache\CacheItemPoolInterface`.
use Symfony\Component\Cache\Adapter\AbstractAdapter;
65
145
66
-
$tpl = new Template(
146
+
$templateStorage = new FilesystemStorage('/path/to/templates');
147
+
$template = new Template(
148
+
$templateStorage,
67
149
/**
68
150
* Symfony's AbstractAdapter::createSystemCache() returns the best possible adapter that your runtime supports.
69
151
* Generally, it will create a cache via PHP files (Opcache must be enabled via opcache.enable in php.ini), and chain that with APCu if your system supports it.
0 commit comments