[commits] [Wiki] changed: Doc/Dev/ConversionH6

[Ralf Lang (B1 Systems GmbH)]

rlang  Sun, 14 Mar 2021 09:50:42 +0000

Modified page: https://wiki.horde.org/Doc/Dev/ConversionH6
New Revision:  5
Change log:  Some updates and progress marks

@@ -6,40 +6,42 @@

  * Unnamespaced code mostly follows Horde 5 Coding standards and very  
little conversion requirements
  * Most of the upgrade requirements are only targeted at namespaced code
  * With some necessary exceptions, Horde 6 should be able to  
cooperate with Horde 5-ish apps and libraries with very little  
modification for composer compat
-* Deprecate PSR-0 autoloading but don't break it intentionally.
+* Deprecate PSR-0 autoloading but don't break it intentionally.  
Unconditional require/require_once/include to paths outside the  
library's own lib or src dir need to check for the require'd class  
first (likely breaks in H6 via composer).
+[Unnamespaced code still needs Horde_Autoloader's slightly different  
approach than composer's autoloader]
  * Consider: Horde 5 Framework lived out 2012-2021, I would like  
Horde 6 to be intentionally shortlived, deprecating more stuff over  
time.
-* Allow a very smooth transition path, avoid big bang changes.
+* Allow a very smooth transition path, avoid big bang changes. [STILL TRUE]

  +++ Exceptions to the rule
  * Most of the upgrade requirements are only targeted at namespaced code

  +++ Mandatory

-* Horde:: is deprecated
-* [rla thinks] we should adopt PSR-2, PSR-12 wholesale with an  
optional opt-out for protected/private underscoring
-* Composer based setup must work with all libraries we intend to keep
+* Horde:: is deprecated [NO REAL REPLACEMENT YET]
+* [rla thinks] we should adopt PSR-2, PSR-12 wholesale with an  
optional opt-out for protected/private underscoring [RLA DOES THIS  
ALREADY]
+* Composer based setup must work with all libraries we intend to keep  
[SOLVED]
  * [rla thinks] Deprecate Horde_Forms usage. Keep it where it is  
until we can refactor, but make it clear this is a legacy concept
-* Update Horde_Core to support both namespaced apps non-namespaced  
apps and mixed.
-* Update Horde_Test to support both namespaced and unnamespaced unit tests
-* Unit Tests must support the current stable phpunit
-* Check all pear package dependencies if they are also available via  
packagist or a proper composer channel rather than pear
+  * Looked into it. There's a few parts to easily refactor when  
converting to namespaced, with some BC breaks but very schematic  
remedy. This will reduce warnings and improve compat with newer PHPs.  
It will really make Form more attractive.
+* Update Horde_Core to support both namespaced apps non-namespaced  
apps and mixed. [ONGOING]
+* Update Horde_Test to support namespaced unit tests (PHPUnit 9 spews  
warnings for unit test classnames different than file name, so there  
is little use in BC here)
+* Unit Tests must support the current stable phpunit [WIP]
+* Check all pear package dependencies if they are also available via  
packagist or a proper composer channel rather than pear [MOSTLY DONE]

  * Update skeleton to use
    * Horde Controllers,
    * Namespacing,
    * Type Hints where appropriate and
-  * Model Interface and Rdo implementation rather than driver architecture
+  * Model Interface and Rdo implementation rather than driver  
architecture [NOT YET DONE]

  +++ Optional / Best Practice

  * Try to drop usage of pear libraries if we only use little portions  
of their api
   * Consider if there is a more modern alternative available on packagist
   * Consider if it is easy to
-* Unbundle bundled code if you can, use composer dependencies
+* Unbundle bundled code if you can, use composer dependencies  
[UNBUNDLED phpunit, sabredav]
  * Maintain a branch or fork of Skeleton to showcase Horde Ajax  
Framework and an SPA frontend
-* All URL generation should be moved to Horde_Routes_UrlWriter driven  
by config/routes.php
+* All URL generation should be moved to Horde_Routes_UrlWriter driven  
by config/routes.php [NOT DONE]
  * A more copy/paste ready boilerplate for ClassLevelDocBlock,  
FileLevelDocBlock, MethodLevelDocBlock

  +++ Exceptions To The Rule

@@ -58,42 +60,42 @@
    * DISCUSS: Any arguments for calling it Horde\Horde? Should we  
rename/alias the base app horde/base altogether?

  * If a library has an interface or base class Horde_$Name, promote  
it to either:
    - Horde\$Name\$Name
-  - Horde\$Name\Interface
+  - Horde\$Name\$NameInterface
    - Horde\$Name\Base
    - Horde\$Name\Constants
    - In case of base classes, re-think if we are not better off with  
an interface and some trait


  * Horde:: is Horde\Core\Horde:: though I think we should re-think  
using it at all
  * Un-namespaced controllers go to App\, namespaced controllers go to  
src/Controller
  * Un-namespaced library code goes to lib/
-* Namespaced library code goes to src/.
+* New or converted namespaced library code goes to src/.


  +++ Optional

  * Unnamespaced code should be preceded with backslash \ to ensure we  
do not run into issues with namespaced derived classes or use cases
-
+  * Do it where it prevents breaks or where . Don't waste effort.
  +++ Exceptions to the rule

-* Code which was already namespaced before Horde 6 may be left in  
lib/ if other unnamespaced code depends on it
-
-
-
-++ PHPDoc / Type Hints / Type Declarations
-
+* Code which was already namespaced before Horde 6 may be left in  
lib/ if other unnamespaced code depends on it
+
+
+
+++ PHPDoc / Type Hints / Type Declarations
+
  Remember Liskov:
  * Interface/Base class parameters should be as specific as possible.  
Derived/Implementing classes can only accept the same or less specific  
definitions
  * Interface/Base class return type parameters should be as  
unspecific as makes sense. Derived/Implementing classes can announce  
to return the same or more specific definitions.

-
-+++ Mandatory
-
+
++++ Mandatory
+
  * PHPDoc all parameters and return values, regardless if you have  
typehinted them.
  * Prefer A|B|null over "mixed"
-
+
  +++ Optional

  * Parameter Type hints for string, int, boolean SHOULD be added to  
the namespaced interfaces where possible
  * Parameter Type hints for classes SHOULD be added to be added to  
the namespaced interfaces where possible.
@@ -126,9 +128,9 @@
    * Horde\Core\Config\

  * for $page_output:
    * ?
-
+
  * for $__autoload

  +++ Mandatory

@@ -147,9 +149,9 @@

  As Horde has evolved over the years, we have different types of  
classes, sometimes even mixed.

  * Classes which implement create-on-the-fly objects with no/few  
dependencies or are mostly static, e.g. Horde_Url, Horde_Date,  
Horde_String
-* Classes which have one or few instances to cover most or all use  
cases, e.g. the DB Driver, the registry. They will typically provided  
by the injector directly or via a factory without explicit parameters
+* Classes which have one or few instances to cover most or all use  
cases, e.g. the DB Driver, the registry. They will typically be  
provided by the injector directly or via a factory without explicit  
parameters
  * Messy stuff which cannot decide if it is a factory or a base class  
or wants composition, e.g. Horde_Form, Horde_Rpc
  * Classes which are intended as Per-Entity objects

  +++ Mandatory
@@ -163,11 +165,11 @@
  <code type="php">
         // Use a factory to get an implementation
         // In case the factory cannot be autowired itself, you need  
to register how to get it first.
          
$injector->bindFactory(Horde\Kronolith\Calendar\Resource::class,  
Horde\Kronolith\Calendar\Factory::class, 'create')
-       // In case you want a specific implementation and it can be  
autowired, just bind it.
+       // In case you want a specific implementation and it can be  
autowired, just bind it.
          
$injector->bindImplementation(Horde\Kronolith\Renderer::class,  
Horde\Kronolith\Renderer\Default::class);
-</code>
+</code>

  * Note there are no strings, this is the class itself - ::class  
returns the fully qualified strings
  * If you have imported the class with use, you can just use the  
imported name:

@@ -180,9 +182,9 @@
         // In case the factory cannot be autowired itself, you need  
to register how to get it first.
         $injector->bindFactory(Resource::class,  
CalendarFactory::class, 'create')
         // In case you want a specific implementation and it can be  
autowired, just bind it.
         $injector->bindImplementation(Renderer::class,  
RendererDefault::class);
-</code>
+</code>


  * Registering an implementation by an arbitrary string is still  
legal, we even might need it for bc compat with some designs.
  <code type="php">
@@ -205,9 +207,9 @@

  +++ Required

  * include, require and require_once should only ever happen to setup  
autoloading or as part of the autoloader or related to non-php code  
(templates, data)
-* make all explicit require/require_once check if the required class  
is already available for loading
+* make all explicit require/require_once check if the required class  
is already available for loading.

  * At least for now, we should not drop Horde\Autoloader
  * Horde\Autoloader must always act AFTER the composer autoloader, not first

@@ -217,9 +219,9 @@

  +++ UNCLEAR

  * Do we still want to support git-tools setups?
-
+ * I have implemented some basic git handling in components now.

  + package specific notes
  ++ Horde\Injector
  +++ Optional
@@ -236,9 +238,9 @@
  ++ Horde\Core
  Mandatory:

  * Provide an alternative for Horde_PageOutput which only returns  
strings rather than doing output (needed, otherwise controllers are  
littered with ob_start())
-* Provide a type to wrap horde config array for DI
+* Provide a type to wrap horde config array for DI [DONE]
  * A lot of class names must be fixed for namespacing

  Optional:
  * Registry (probably rather 6.1) Provide a more robust inter-app API  
but don't break the current inter-app API for now
@@ -247,9 +249,9 @@
   * Move vfs/webdav implementations to Horde\$App\Api\Vfs

  ++ Horde\Rpc
  Mandatory:
-* Fix the signature missmatch errors
+* Fix the signature missmatch errors [NOT DONE]
  Optional:
   * Default to JsonRpc rather than XmlRpc
   * Refactor to controller framework