README

Universal package, following the #East programming philosophy, build on Teknoo/East-Foundation (and Teknoo/Recipe), and implementing a basic CMS to display dynamics pages with different types and templates.

Example with Symfony

//These operations are not reauired with teknoo/east-website-symfony

//config/packages/east_website_di.yaml:
di_bridge:
    definitions:
        - '%kernel.project_dir%/vendor/teknoo/east-website/src/di.php'
        - '%kernel.project_dir%/vendor/teknoo/east-website/infrastructures/doctrine/di.php'

//bundles.php
...
Teknoo\East\WebsiteBundle\TeknooEastWebsiteBundle::class => ['all' => true],

//In doctrine config (east_website_doctrine_mongodb.yaml)
doctrine_mongodb:
    document_managers:
        default:
            auto_mapping: true
            mappings:
                TeknooEastCommon:
                    type: 'xml'
                    dir: '%kernel.project_dir%/vendor/teknoo/east-common/infrastructures/doctrine/config/universal'
                    is_bundle: false
                    prefix: 'Teknoo\East\Common\Object'
                TeknooEastWebsite:
                    type: 'xml'
                    dir: '%kernel.project_dir%/vendor/teknoo/east-website/infrastructures/doctrine/config/universal'
                    is_bundle: false
                    prefix: 'Teknoo\East\Website\Object'
                TeknooEastWebsiteDoctrine:
                    type: 'xml'
                    dir: '%kernel.project_dir%/vendor/teknoo/east-website/infrastructures/doctrine/config/doctrine'
                    is_bundle: false
                    prefix: 'Teknoo\East\Website\Doctrine\Object'

//In security.yaml
security:
    providers:
        with_password:
            id: 'Teknoo\East\CommonBundle\Provider\PasswordAuthenticatedUserProvider'

    password_hashers:
        Teknoo\East\CommonBundle\Object\PasswordAuthenticatedUser:
            algorithm: '%teknoo.east.common.bundle.password_authenticated_user_provider.default_algo%'


//In routes/website.yaml
admin_website:
    resource: '@TeknooEastWebsiteBundle/config/admin_routing.yaml'
    prefix: '/admin'

admin_common:
    resource: '@TeknooEastCommonBundle/config/admin_routing.yaml'
    prefix: '/admin'

website:
    resource: '@TeknooEastWebsiteBundle/config/routing.yaml'

Environments

Contents, posts and items belong to an environment of the website, to prepare new versions of the pages, menus and posts on the same instance, visible only when their environment is selected. The root environment is default, always available, without parent. Other environments are declared in the DI (a PHP-DI value or a Symfony parameter, each environment has exactly one parent):

//In config/services.yaml
parameters:
    teknoo.east.website.definitions.environments:
        validation: 'default'
        testing: 'default'
        test-a: 'testing'
    //Optional, environments absent from this list are public, `default` is always public
    teknoo.east.website.definitions.environments_access:
        testing: ['ROLE_TESTER', 'ROLE_ADMIN']
        test-a: ['ROLE_TESTER']

The service teknoo.east.website.environments (Teknoo\East\Website\Object\Environments, iterable and read only) lists all defined environments, indexed by name, with default. The admin forms of contents, posts and items have a dropdown environment (the JSON API accepts and returns the name under the key environment, groups api and crud).

On the front, a visitor selects an environment with the request parameter website-env (POST or GET); the choice is stored into the session (East Foundation session, key website-env) and reused by the next requests. The chain of the selected environment (itself and its ancestors until default) is the only one visible: with test-a, the contents of test-a, testing and default are served, those of validation are not. The front queries, the lists of posts and tags, and the menu generator (items linked to a content out of the chain are skipped) are filtered.

An unknown environment, or an environment restricted to roles the current user (an East Common UserInterface) does not own, is an error 404, the session is not changed.
A value in session that is no longer valid is removed from the session, and the default environment is used.
Slugs stay unique for the whole website: an environment is a visibility scope, not a copy of a page per environment.

The environment is stored as a string in MongoDB (custom ODM type environment, registered by the Symfony bundle when the Doctrine MongoDB bundle is enabled, or by infrastructures/doctrine/di.php with a plain PHP-DI container). Documents created before this feature, without the field, belong to the default environment: no migration is needed. The selected environment is available to the steps as the ingredient Teknoo\East\Website\Object\Environment (and environment), and to the views in the parameters bag (environment, and a menuGenerator scoped to it).

JSON API

East Website ships routes for a JSON API. They reuse the same endpoints as the HTML routes, only the parameters change (api: 'json', JSON templates, HTTP methods). The admin API covers items, contents, posts, comments, types, tags, users and media. The public API covers contents, posts, lists of posts, and posting comments.

Requirements: symfony/serializer (with framework.serializer.enabled: true), symfony/twig-bundle 7.3+, and the EastFoundationBundle (which registers the East normalizer). Like in Space, the CSRF protection must be enabled for the application's forms (framework.csrf_protection): East Common disables it on forms of API routes.

//In routes/website_api.yaml, API routes must be imported BEFORE `routing.yaml` (its route `/{slug}` catches
//all paths)
api_admin_website:
    resource: '@TeknooEastWebsiteBundle/config/api_admin_routing.yaml'
    prefix: '/api/v1/admin'

api_admin_website_blog:
    resource: '@TeknooEastWebsiteBundle/config/api_admin_routing_blog.yaml'
    prefix: '/api/v1/admin'

api_website:
    resource: '@TeknooEastWebsiteBundle/config/api_routing.yaml'
    prefix: '/api/v1'

api_website_blog:
    resource: '@TeknooEastWebsiteBundle/config/api_routing_blog.yaml'
    prefix: '/api/v1'

api_website_blog_comment:
    resource: '@TeknooEastWebsiteBundle/config/api_routing_blog_comment.yaml'
    prefix: '/api/v1'

Admin routes follow the pattern (for item, content, post, type, tag, user and media):

POST|PUT /<element>/new: creates an element, the client is redirected to the element.
GET|POST|PUT /<element>/{id}: returns or updates an element (media can only be read).
GET /<element>s (/media for media): lists elements, with the query parameters page, order and direction.
POST|DELETE /<element>/{id}/delete: deletes an element, the deleted element is returned.
Comments of posts: GET /post/{postId}/comments, GET|POST|PUT /post/{postId}/comment/{id} (moderation) and POST|DELETE /post/{postId}/comment/{id}/delete.

Public routes are GET /content/{slug} (the home page is /content/default), GET /post/{slug}, GET /posts, GET /posts/by/{tag} and POST|PUT /post/{slug}/comment.

Bodies can be sent as JSON (with the header Content-Type: application/json, without the form's name, and only sent fields are updated) or urlencoded/multipart (fields under the form's name, like tag[name]). Media are uploaded with a multipart body. The key publish in a body publishes a content or a post.

Responses use the envelope {"meta": {...}, "data": ...}:

an element: meta contains its id and its class,
a list: meta contains totalPages, page and count,
invalid forms: status 400, {"meta": {"errors": true}, "data": {".field": "message"}} when the root form has errors (including errors bubbled from its fields), else the element is returned with the status 400 (like in Space),
errors: {"meta": {"error": true}, "data": {"code": 404, "message": "..."}}.

Objects are normalized according to groups: api (admin lists), crud (admin elements), digest (deleted elements) and public (public API: parts are sanitized, and the author's email, the template and the remote IP of comments are never exported). JSON templates are in @TeknooEastWebsite/api/ and can be overridden in templates/bundles/TeknooEastWebsiteBundle/api/.

Security warning: the admin API is shipped without authentication and CSRF protection is disabled in API mode. Applications must protect ^/api/v1/admin with a stateless authentication (like a JWT), never with a session cookie. Applications should also rate-limit the public comment endpoint.

CLI client

Experimental: a command line client of this API lives in tools/api-client/. It is provided as an experimental tool: its commands, its options and its configuration file may change at any time, outside of the semantic versioning of the library.

It is a Symfony Console application, distributed as a phar (make tools-phar), exposing every function of the API grouped by domain (website:type:create, website:post:list, website:front:post:get...). website:auth:login logs in with a username and an API key, gets a JWT and writes the configuration file ./east-website.json, read by all the other commands (website:auth:logout deletes it). It prints JSON on stdout and errors on stderr with stable exit codes, so it can be used by scripts and AI agents. See tools/api-client/README.md.

Support this project

This project is free and will remain free. It is fully supported by commercial activities of SASU Teknoo Software and EIRL Richard DELOGE. If you like it and help me maintain it and evolve it, don't hesitate to support me on Patreon or Github.

Thanks :) Richard.

Credits

EIRL Richard Déloge - https://deloge.io - Lead developer. SASU Teknoo Software - https://teknoo.software

About Teknoo Software

Teknoo Software is a PHP software editor, founded by Richard Déloge, as part of EIRL Richard Déloge. Teknoo Software's goals : Provide to our partners and to the community a set of high quality services or software, sharing knowledge and skills.

License

East Website is licensed under the 3-Clause BSD License - see the licenses folder for details.

Installation & Requirements

To install this library with composer, run this command :

composer require teknoo/east-website

To start a project with Symfony :

symfony new your_project_name new
composer require teknoo/east-website-symfony

This library requires :

* PHP 8.1+
* A PHP autoloader (Composer is recommended)
* Teknoo/Immutable.
* Teknoo/States.
* Teknoo/Recipe.
* Teknoo/East-Foundation.
* Optional: Symfony 6.3+ (for administration)

News from Teknoo Website 9.x

This library requires PHP 8.1 or newer and it's only compatible with Symfony 6.3 or newer.

Support last version of PHP DI 7 et Diactoros 3
Automatic cleaning of rendered HTML thanks to tidy

News from Teknoo Website 8.x

This library requires PHP 8.1 or newer and it's only compatible with Symfony 6.2 or newer.

Users and Media are migrated to East Common
Dynamic texts can be sanitized thanks to Symfony Sanitizer (if you use Symfony Form)
- You can persists directly sanitized contents
- Add helpers to fetch directly these sanitized contents
Add ReadOnlyArray to simulate a read only array'
Optimization of Menu Generator

News from Teknoo Website 7.x

This library requires PHP 8.1 or newer and it's only compatible with Symfony 6.0 or newer.

Support Recipe 4.1.1+
Support East Foundation 6.0.1+
Public constant are final
Block's types are Enums
Direction are Enums
Use readonly properties behaviors on Immutables
Remove support of deprecated features removed in Symfony 6.0 (Salt, LegacyUser)
Use (...) notation instead array notation for callable
Enable fiber support in front endpoint
QueryInterface has been splitted to QueryElementInterface and QueryCollectionInterface to differentiate queries fetching only one element, or a scalar value, and queries for collections of objects.
LoaderInterface::query method is only dedicated for QueryCollectionInterface queries.
a new method LoaderInterface::fetch is dedicated for QueryElementInterface queries.

Warning * : All legacy user are not supported from this version. User's salt are also not supported, all users' passwords must be converted before switching to this version.

News from Teknoo Website 6.x

This library requires PHP 8.0 or newer and it's only compatible with Symfony 5.3 or newer

Add UserInterface to represent and User in a Eastt Website / WebApp.
Add AuthDataInterface to represent any data/credentials, able to authenticate an user
Update User class to following the previeous interface
Split authentications data from User class to a dedicated class StoredPassword
Support password already hashed into StoredPassword
Update Doctrine ODM mappingg about User ans add StoredPassword
Support third-party authentication.
Add ThirdPartyAuth to store ids data from thrid party needed to authenticate an user.
Add AbstractPassordAuthUser to wrap password logic in Symfony User for LegacyUser and PasswordAuthenticatedUser.
AbstractUser can be also used for non password authenticated user.
Create PasswordAuthenticatedUser to implements new Symfony's interface PasswordAuthenticatedUserInterface
Update SymfonyUserWriter implementation in Symfony to hash password only when its needed.
Rework UserProvider to PasswordAuthenticatedUserProvider to return a LegacyUser if the user use the legacy Symfony behavior with a slug or a PasswordAuthenticatedUser. It is able to migrate logged user to the new behavior, update the hashed ppassword passed by Symfony and remove salt.
Some QA fixes on PHPDoc
Remove deprecated ViewParameterInterface
Remove deprecated Symfony User class
Create StoredPasswordType to manage new user in a Symfony Form.
Fix some bug in admin routes.
Update annd fix some minor bug in Doctrinemapping
Create OAuth2Authenticator, built on KNPU OAuth2 client bundle to authenticate user thanks to a OAuth2 provider.

News from Teknoo Website 5.x

This library requires PHP 8.0 or newer and it's only compatible with Symfony 5.2 or newer

Migrate to PHP 8.0
Writers services, Deleting services, and interfaces use also Teknoo\East\Common\Contracts\Object\ObjectInterface.
Create Teknoo\East\Common\Contracts\Object\ObjectInterface, Teknoo\East\Common\Contracts\Object\IdentifiedObjectInterface extends it dedicated to non persisted object, manipulable by other components
Update steps and forms interface to use this new interface
Replace ServerRequestInterface to MessageInterface for ListObjectAccessControlInterface and ObjectAccessControlInterface
Switch Render steps to MessageInterface
Add ExprConversionTrait::addExprMappingConversion to allow your custom evaluation of expression
Add ObjectReference expression to filter on reference
CreateObject step has a new parameter $workPlanKey to custom the key to use to store the new object in the workplan
CreateObject, DeleteObject, LoadObject, SaveObject and SlugPreparation use Teknoo\East\Common\Contracts\Object\ObjectInterface instead Teknoo\East\Common\Contracts\Object\IdentifiedObjectInterface. SaveObject pass the id only if the object implements this last object

News from Teknoo Website 4.x

This library requires PHP 7.4 or newer and it's only compatible with Symfony 4.4 or newer

Migrate to Recipe 2.3+ and Tekno 3.3
Migrate all classics services endpoints to Plan and Recipe.
Remove all traits in main namespace with implementation in infrastructures namespaces.
All plans and recipes, and majors of step are defined in the main namespace, only specialized steps are defined in infrastructures namespace.
Remove AdminEditEndPoint, AdminListEndPoint, AdminNewEndPoint, ContentEndPointTrait and MediaEndPointTrait.
Update Symfony configuration to manage this new architecture. Remove all services dedicated for each objects in Website, replaced by only agnostic endpoint. All configuration is pass in route.

News from Teknoo Website 3.x

This library requires PHP 7.4 or newer and it's only compatible with Symfony 4.4 or newer

Migrate to Doctrine ODM 2
Migrate to new GridFS Repository
Migrate Gedmo's Timestamp to intern function and service
Migrate Gedmo's Slug to intern function and service
Migrate to Doctrine XML Mapping
Reworking Translation : Fork Gedmo Translation, clean, simplify, rework, in East philosophy
Remove Gedmo
Create new Translation configuration
Pagination Query support countable
ContentType and ItemType are not hardcoded to use DocumentType, but a Type passed in options via the EndPoint
Optimize menu to limit requests
Expr In Agnostic support
Change Doctrine Repository behavior to create classes dedicated to ODM
Create Common repository for non ODM with fallback feature
Autoselect Good Repository in DI
Migrate MediaEndPoint into ODM namespace
Add ProxyDetectorInterface and a snippet into DI to detect if an object is behind a proxy agnosticaly
Require to East Foundation 3.0.0
Fix errors in services definitions
Change exception management into MediaEndPoint

News from Teknoo Website 2.x

This library requires PHP 7.4 or newer and it's only compatible with Symfony 4.4 or newer, Some change causes bc breaks :

PHP 7.4 is the minimum required
Replace array_merge by "..." operators
Remove some PHP useless DockBlocks
Switch to typed properties
Most methods have been updated to include type hints where applicable. Please check your extension points to make sure the function signatures are correct. _ All files use strict typing. Please make sure to not rely on type coercion.
Set default values for Objects.
Set dependencies defined into PHP-DI used in Symfony as synthetic services into Symfony's services definitions to avoid compilation error with Symfony 4.4
Enable PHPStan in QA Tools and disable PHPMd
Enable PHPStan extension dedicated to support Stated classes

Contribute :)

You are welcome to contribute to this project. Fork it on Github

teknoo / east-website

Package info

Security

Fund package maintenance!

Statistics