friendica-directory/docs/Concepts.md

59 lines
2.9 KiB
Markdown

# Friendica Directory Project Concepts
## Dependency Injection
Friendica Directory uses a Service Container that holds all the services that can potentially be needed.
It is defined in `src/dependencies.php`.
However, this Container isn't globally available to classes. Instead, we use factory classes and closures to construct each classes with just the required services.
This way, we can test classes in isolation without having to care for a full-featured Container.
## Entry points, Controllers and Routes
There are 3 entry points to the Friendica Directory:
- The web server with the `Slim\App` class, taking HTTP requests and outputting HTML pages.
- The command-line console with the `Friendica\Directory\Controllers\Console` class taking command-line parameters and outputting plain text.
- The background task with the `Friendica\Directory\Controllers\Cron.php` class with no input and no output.
Next up, there are a variety of Controllers in the subfolders of `src/classes/Controllers` depending on the intended use:
- `Api/` for web controllers outputting JSON.
- `Console/` for the various sub console commands.
- `Web/` for the displayed HTML pages.
To match the latter with the former, Routes are defined in `src/classes/Routes` based on the entry point.
Multiple routes can reference the same Controller, we use this feature to offer the same sub console for different spelling of the same command.
More importantly, Routes are the above-mentioned factory classes tasked with instantiating the Controllers with the correct services.
## Database migrations
In `src/sql` can be found the base SQL schema as it was at the start of the project, and in `src/migrations/up` the various additional SQL scripts that have been added to it.
Scripts are named after the database version it is upgrading the schema to, and is incremented each time we need to alter the schema.
This allows individual Friendica Directory installs to seamlessly upgrade their schema when pulling the new code, no matter how old the last update was.
To update to the latest schema, simply run `bin/console dbupdate`.
## PHP Templating
Friendica Directory relies on pure PHP templates. The base layout is `src/templates/layout.phtml`, full page templates are located in the same directory and sub-templates are found in the subfolders.
The main challenge with PHP templates is escaping dynamic values to prevent XSS attacks.
This is done using [Zend Escaper](https://framework.zend.com/manual/2.4/en/modules/zend.escaper.introduction.html) and convenience wrapper methods have been added to the PHPRenderer to be able to use it in the templates.
Sample usage:
```php
<script type="text/javascript">
var foo = <?php echo $this->escapeJs($js)?>;
</script>
<style>
<?php echo $this->escapeCss($css); ?>
</style>
<div class="<?php echo $this->escapeHtmlAttr($attr)?>">
<?php echo $this->e($body)?>
<a href="?url=<?php echo $this->escapeUrl($attr)?>">Link</a>
</div>
```