|
| 1 | +# Jinja PHP |
| 2 | + |
| 3 | +A minimalistic **zero-dependency** PHP implementation of the Jinja templating engine, specifically designed for parsing and rendering |
| 4 | +machine learning (ML) chat templates. This project is heavily inspired by HuggingFace's Jinja template engine in |
| 5 | +JavaScript, intended primarily for ML chat templates, but is versatile enough to be used for general purposes of parsing |
| 6 | +most Jinja templates. |
| 7 | + |
| 8 | +## Installation |
| 9 | + |
| 10 | +Install Jinja PHP through Composer: |
| 11 | + |
| 12 | +```shell |
| 13 | +composer require codewithkyrian/jinja-php |
| 14 | +``` |
| 15 | + |
| 16 | +## Usage |
| 17 | + |
| 18 | +Here’s how you can use Jinja PHP to render a template: |
| 19 | + |
| 20 | +```php |
| 21 | +$sourceString = "{{ bos_token }}{% for message in messages %}{% if (message['role'] == 'user') != (loop.index0 % 2 == 0) %}{{ raise_exception('Conversation roles must alternate user/assistant/user/assistant/...') }}{% endif %}{% if message['role'] == 'user' %}{{ '[INST] ' + message['content'] + ' [/INST]' }}{% elif message['role'] == 'assistant' %}{{ message['content'] + eos_token + ' ' }}{% else %}{{ raise_exception('Only user and assistant roles are supported!') }}{% endif %}{% endfor %}"; |
| 22 | +$args = [ |
| 23 | + 'messages' => [ |
| 24 | + ['role' => 'user', 'content' => 'Hello!'], |
| 25 | + ['role' => 'assistant', 'content' => 'Hi! How are you?'], |
| 26 | + ['role' => 'user', 'content' => 'I am doing great.'], |
| 27 | + ['role' => 'assistant', 'content' => 'That is great to hear.'], |
| 28 | + ], |
| 29 | + "add_generation_prompt" => true, |
| 30 | + "bos_token" => "<s>", |
| 31 | + "eos_token" => "</s>", |
| 32 | + "unk_token" => "<unk>", |
| 33 | +]; |
| 34 | + |
| 35 | +$template = new Template($sourceString); |
| 36 | + |
| 37 | +$rendered = $template->render($args); |
| 38 | +// <s>[INST] Hello! [/INST]Hi! How are you?</s> [INST] I am doing great. [/INST]That is great to hear.</s> |
| 39 | +``` |
| 40 | + |
| 41 | +## Advanced Usage |
| 42 | + |
| 43 | +Jinja PHP supports various control structures from Jinja templates. Here are some examples: |
| 44 | + |
| 45 | +### Conditional Statements: |
| 46 | + |
| 47 | +```php |
| 48 | +{% if user.isActive %} |
| 49 | + Hello, {{ user.name }}! |
| 50 | +{% else %} |
| 51 | + Hello, Guest! |
| 52 | +{% endif %} |
| 53 | + |
| 54 | +``` |
| 55 | + |
| 56 | +### For Loops |
| 57 | + |
| 58 | +```php |
| 59 | +<ul> |
| 60 | +{% for user in users %} |
| 61 | + <li>{{ user.name }}</li> |
| 62 | +{% else %} |
| 63 | + <li>No users found.</li> |
| 64 | +{% endfor %} |
| 65 | +</ul> |
| 66 | +``` |
| 67 | + |
| 68 | +```php |
| 69 | +{% for user in users %} |
| 70 | + {{ loop.index }} - {{ user.name }} |
| 71 | +{% endfor %} |
| 72 | +``` |
| 73 | + |
| 74 | +### Variable Filters |
| 75 | + |
| 76 | +```php |
| 77 | +{{ "Hello World!"|lower }} |
| 78 | +``` |
| 79 | + |
| 80 | +## Comprehensive Feature Support |
| 81 | + |
| 82 | +Jinja PHP is designed to be robust and feature-rich, offering support for a wide range of functionalities beyond the |
| 83 | +basics of templating. This includes handling exceptions, using default string methods like `strip()` or `upper()`, |
| 84 | +working with dictionaries, and much more. If there's a feature you need that isn't currently implemented in Jinja PHP, |
| 85 | +we encourage you to [request it](https://github.com/codewithkyrian/jinja-php/issues/new). Additionally, if you're |
| 86 | +proficient with PHP and understand the internals of templating engines, consider contributing to the project by |
| 87 | +submitting a pull request with your proposed feature. |
| 88 | + |
| 89 | +## Testing |
| 90 | + |
| 91 | +Jinja PHP comes with a suite of tests to ensure functionality remains consistent and reliable. To run the tests: |
| 92 | + |
| 93 | +``` |
| 94 | +composer test |
| 95 | +``` |
| 96 | + |
| 97 | +## Contributors |
| 98 | + |
| 99 | +- [Kyrian Obikwelu](https://github.com/CodeWithKyrian) |
| 100 | +- Other contributors are welcome. |
| 101 | + |
| 102 | +## Acknowledgements |
| 103 | + |
| 104 | +- [Hugging Face](https://huggingface.co/) for their work on ML chat templates. |
| 105 | +- The Jinja template engine for Python, which served as the primary inspiration for this project. |
| 106 | + |
| 107 | +## Support |
| 108 | + |
| 109 | +If you find any issues or have a question, feel free |
| 110 | +to [open an issue](https://github.com/CodeWithKyrian/jinja-php/issues/new/choose) in the repo. |
| 111 | + |
| 112 | +## License |
| 113 | + |
| 114 | +This project is licensed under the MIT License. See |
| 115 | +the [LICENSE](https://github.com/codewithkyrian/jinja-php/blob/main/LICENSE) file for more information. |
0 commit comments