[commits] [Wiki] created: Doc/Dev/Skeleton

[Ralf Lang (B1 Systems GmbH)]

rlang  Sat, 27 Nov 2021 14:34:29 +0000

Created page: https://wiki.horde.org/Doc/Dev/Skeleton

[[toc]]

+ Skeleton Application

++ Description

Skeleton is an application template. You can use it to kickstart  
development, see ((CreatingYourFirstModule|Creating Your First Module)).
It is also an educational example, trying to keep up with the  
framework's most recent best practices. Comments are decidedly wordy.

++ Usage

Skeleton does not provide any end user value. It does generate a DB  
schema, a portal block and a preference setting, but none of it  
implements any particular feature.
The list shown in the only UI screen is generated from a mock array.

++ Bugs

List any tickets on http://bugs.horde.org/ that cover this issue or  
are relevant to it.

++ People

Ralf Lang for the H6 upgrade
Jan Schneider and Chuck Hagenbuch for the original content.

++ Resources

Include links to protocol descriptions, specifications, RFCs, external  
applications, presentations on http://horde.org/papers/ or elsewhere  
that are relevant, articles, API docs from http://dev.horde.org/ -  
anything that might be useful to someone working on this.

++ UPGRADING

As skeleton is not designed to be of any use, this section describes  
evolution of best practice as it becomes available. These MAY also be  
applied to other applications as time permits and is feasible.

Because skeleton is also used as a clone template, the version history  
should not be spammed with entries reflecting the changes.

+++ Registry Snippet

A registry snippet has been placed in doc/registry.d/ - this prevents  
skeleton from showing up as a button with no text when installed. The  
snippet is automatically picked up by the horde-installer-plugin and  
copied to the var/config/horde/registry.d dir unless a file already  
exists. This is symlinked to web/horde/config/registry.d for BC reasons.

+++ Routes/Controllers: No more list.php and index.php

The list.php UI page has been moved to the routes/controller  
framework. TODO link to a more detailed article on that framework  
feature.
The index.php is no longer needed. With a sufficiently recent version  
of the horde/horde-deployment (2021-11-27 and beyond), there is a  
rewrite rule that forwards missing directory indexes to the  
routes/controller framework. A default route catches all links which  
are not handled by other routes or files

+++ Constructor injection replaces globals

These globals are avoided:

- $notification: replaced by constructor injection. Requires  
sufficiently recent horde/core (2021-11-27 and beyond)
- $registry: Replaced by constructor injection
- $page_output: Replaced by constructor injection
- $session: Replaced by constructor injection

+++ Usage of injector (DIC) in controllers

The injector is now offered by constructor injection. We pass the  
namespaced version, not the unnamespaced wrapper. The $injector global  
should not be used.
The injector SHOULD not need to be passed to controllers at all but  
there is too much horde code out there that gets and uses the injector  
as a replacement for missing factories, catalogs, service locators  
etc. Plans are to keep the injector in the signature but replace it  
with a wrapper that logs any uses of getInstance as debug messages.  
People need time to adopt.

+++ src/ code removes underscores for most non-publics
Traditional code uses the PEAR convention, prepending names with underscores:
- for private and protected properties
- for private and protected function names
- for technically public code which is implementation specific

These underscores have been removed unless
- there is a name clash with another method
- a protected variable or method needs to stay compatible with parent  
or child code which cannot currently be refactored

+++ lib/ code removed or turned into wrappers

Ongoing:

Original code in lib either is turned into mere wrappers or removed  
altogether. As applications are not inherited from or used like  
libraries, only the framework's integration points need to be kept as  
wrappers:

- lib/Application.php - Used for inter-app and DAV calls. Also  
contains fallback definition of the SKELETON_BASE and HORDE_BASE  
constants, though most likely not needed anymore
- lib/Api.php - Used for inter-app and RPC. In real world  
applications, we might see some breakage if we actually use the API,  
as calling code may be liberal with typing. In the case of skeleton,  
the Api is empty anyway.
- lib/Ajax/Application.php - Integration point for the AJAX framework.
- lib/Block/ - Wrappers for all implemented blocks need to be kept  
until the framework learns to also look into /src/Block/ or some  
catalog class.
- lib/Test.php  - The integration point for the health check UI called  
under /horde/test.php. Though skeleton does not really implement any  
useful test


+++ Strict types applied and type hints turned to real types
The strict typing mode is used consistently everywhere in src/.
Most property, parameter and return type hints were turned into actual  
types. Many missing types were added.

Exceptions:
- We know of calling code which does not (yet) behave
- Union types, Stringable etc are PHP 8 only but we currently target  
php 7.4 compatibility
- Resources

+++ Code moves to PSR-4 with unnamespaced wrappers

The code in src/ started out as a copy of the traditional,  
unnamespaced code in lib/ and then got namespaced. In some cases,  
structure and names were change. We want the class name to be useful  
in its most likely use cases without the namespace prepended. To avoid  
confusion or name clashes, factory got moved into the namespace of the  
driver. Horde\Skeleton\Driver\Driver and  
Horde\Skeleton\Driver\DriverFactory may seem like duplication but  
consider:

- Inside the Driver namespace, we save on use statements
- When importing a class to other namespaces, we have a useful name

----
Back to the ((Project|Project List))