We’re starting to bring the various repositories for the Apigility on Expressive initiative into the zendframework GitHub organization, and realized we have a naming problem.
The first has landed: zend-problem-details. We have two more that are about ready:
Hypertext Application Language (HAL) support, currently package “weierophinney/hal”
Caching middleware, currently package “zend-expressive-cache”
The problems we’re running into are:
The code is engineered to work with Expressive, but
is not specific to Expressive; it can be used in any PSR-7/PSR-15 middleware application.
When I chose “zend-problem-details” as a package name, it seemed a no-brainer; it’s an implementation of the Problem Details for HTTP APIs specification (IETF RFC 7807). However, with the other two repositories, we have some questions:
We already have a “zfcampus/zf-hal” package, and don’t want to confuse the two.
The proposed HAL package can provide just OOP functionality around HAL, but it’s intended purpose is to provide PSR-7 response generation, for use within PSR-7/PSR-15 middleware.
The proposed zend-expressive-cache package provides PSR-7/PSR-15 middleware that can cache requests using PSR-16 caching adapters.
We’ve tossed around a few ideas, and would like some feedback:
No special prefix; name the packages semantically. Downside: it’s unclear which packages can be used with Expressive and/or general PSR-7/PSR-15 middleware.
Use zend-expressive- as a package prefix. Potential downside: developers using other middleware stacks do not adopt them, thinking they are specific to Expressive.
Use zend-middleware- as a package prefix. Potential downside: Expressive users have uncertainty about their ability to use the packages within Expressive. Additionally, for packages that do not provide middleware (e.g., the HAL package), the prefix is a misnomer.
Use a different organization like we did with Apigility (which is under the zfcampus org). Discoverability is the downside at that point.
Which options appeal to you? Do you have other suggestions?
Hey Matthew, I see what you’re saying and it’s a bit of a tough one. Of the four proposed options, the one that most stands out for me is zend-middleware- prefix. That way, it’s clear that it’s part of the larger Zend package ecosystem, and it’s also clear that it’s related to middleware. It’s also not inadvertently tying the package to Expressive.
The catch I see with it is that the naming’s a bit bland. It’d be great if 1) there wasn’t the need for a special prefix, 2) they could be given a name which suited their purpose, and 3) they were stored under one, collective, organisation.
While I’m not a big Laravel user, I like how they name their packages. Perhaps the issue of what can the package be used with, such as Expressive or not, or PSR-15 etc, just needs to be spelled out clearly in each package’s documentation.
I wonder if having a zend-psrxx prefix might be an option? zend-psr15-cache and zend-psr15-hal or zend-psr15-problem-details. Might be too long and complicated, but it would signal that they are coded to psr standards and have something to do with PSR-15 middleware - even if they don’t provide middleware themselves. Keep zend-expressive for packages that are designed and hooked in specifically to Expressive like zend-expressive-fastroute.
Whichever you do, adding repository tags in Github would help with the discoverability.
The idea of a -psr#- name part doesn’t make sense across repositories. zend-psr4-router would be a valid extension of such a naming standard and in the context of zf2 such naming is silly. Should only new projects contain the -psr4- prefix?
As technologies advance they share common pieces such as zfcampus: This organization does a specific job and includes everything (and some) it does. But not everything which could belong in zfcampus should belong there such as zf-oauth2-doctrine. As I created libraries which were not core to or in the map of zfcampus I created a new organization to group them, api-skeletons. The examples of zfcampus and api-skeletons show me that grouping new technology into organizations is a flexible enough solution and this is my recommendation: create a new organization to support new tech as it emerges in order to give a diction to the progress and position of a repository in time and function.
p.s. don’t sweat trying to stress that anything is -psr#- and just include it in the docs.
Use the zend- prefix, with an optional prefix of middleware- for packages that provide middleware.
Keep it under the zendframework namespace.
This leaves you with:
zendframework/zend-middleware-cache
zendframework/zend-hal
zendframework/zend-middleware-problem-details
An additional thought is to drop the zend- prefix entirely. Thanks to the prolific use of Composer and Packagist, you should always be seeing the package name in conjunction with the vendor namespace.
I am for droping zend- prefix I always mistype zend packages for example zendframework/servicemanager instead of zendframework/zend-servicemanager I think we have to many zend, we all know it’s from zend
I agree with @TomHAnderson with regards to including -psr#- in the package name, but for a different reason: many of these packages address multiple standards. As an example, Problem Details touches on each of PSR-7, PSR-15, and PSR-11, and may eventually also consume PSR-17. Do we include all of these? What happens when we include another standard?
We will continue to prefix with zend-. This has been our convention all along, and it helps prevent collisions when folks fork our repositories; if we drop the prefix, the chance of a collision goes sky-high (e.g., “authentication”, “validator”, etc. are very common names across frameworks from many different languages!).
The second-level prefix makes sense in many ways, but becomes unwieldy; I’m already a bit dis-satisfied with all the zend-expressive-* repos! However, it is descriptive, and can help separate out packages that touch on multiple domains (e.g., caching for middleware). We’ll continue evaluating this.
We will be adding repository tags; in fact, we’ve already started, but just haven’t rolled them out everywhere yet. We will typically duplicate these within the composer.json as well, to ensure that you can search for those same tags on Packagist. This is likely the best way to provide discovery.
I’m unsure about moving the code to a new organization. Doing so means re-creating existing teams, makes discovery harder and potentially confusing (“why are there Zend Framework packages under organization X? is that a fork?”). However, it also allows us to create semantically named packages that might overlap with existing packages within ZF (e.g., authentication, caching, permissions, etc.). We’ll continue evaluating this option.
Don’t use PSR-XX since a package may implement multiple PSR’s now or in the future. Or a PSR might get dropped in favor of a newer (PSR-0 -> PSR-4).
A zend-expressive- prefix binds a package more or less to expressive.
I wouldn’t use a new organization. Keep everything under zendframework. It was always a question for me if zf-commons was officially a zend organization or some 3rd party group.
So I would use:
zend-middleware- for shared middleware
zend-apigility- for apigility only
zend-expressive- for expressive only
zend-<name> if it doesn’t fit the above like zend-hal.
I guess as long as you have a good readme and tell there what the package does and where it can be used (stand-alone / expressive / apigility / zend-mvc) you should be fine. Maybe add some badges to make it more clear to what group(s) a package belongs…
The only issue I have with including a zendframework package is that I always forget zendframework and just type zend-servicemanager
I think we should use zend-expressive-* prefix naming for anything related to PSR-7 middleware development. This because even if we are PSR-7 compliant, we are using some specific files for Expressive, like the ConfigProvider.
In talking with Enrico offline, the point he’s making is that currently, ConfigProvider implementations are Expressive-specific, as is the means by which we supply factories for a PSR-11 implementation to consume; both are assuming certain application features.
Even if these features are not used by a consumer, they are part of the package, and our primary target audience is Expressive, and secondarily other PSR-7 middleware frameworks.
Similarly, in the Slim ecosystem, the packages are all under the Slim namespace, even when they can be dropped into any PSR-7 middleware application.
I believe that psrX and expressive infixes are bad. The middleware one could be OK but like said before, it could be misleading in some cases.
In case of a cache I would consider two possible ways, both with psr infix, a PSR without a specific number.
Name the package zend-psr-cache so it says it is Zend’s implementation of cache with PSR in mind (it’s compatible with PSR0, PSR1, PSR2, PSR4, PSR7, PSR15, PSR16, possibly more).
Separate the package into two packages: zend-psr-cache with plain framework-agnostic implementation of PSR for cache and zend-middleware-cace with just middlewares depending on zend-psr-cache.
Both ways will differentiate from zend-cache and will be as descriptive as possible not being to long.
This isn’t terribly relevant; the package we’re talking about is a package that provides middleware that composes a PSR-16 cache adapter in order to either (a) serve cached responses, and/or (b) cache responses to serve later. It’s not providing PSR-16 or PSR-6 support, only consuming it.
(By the way, zend-cache will be providing support for both specs in a forthcoming release, without a change in package name.)
So, the point is: what do we name this middleware-centric package?
At this time, we are deciding to use zend-expressive- as a prefix for packages that provide middleware or features that will be consumed by middleware, with the exception of the already released zend-problem-details. Packages will be released under the zendframework GitHub organization to allow us to make use of existing teams, as well as ensure that developers searching for the packages do not need to look under multiple organizations to find them.
The rationale is as follows:
Ensures the package names do not conflict with existing ZF packages. This is particularly important when we consider packages with generic names like “authentication”, “cache”, etc.
Helps identify where these packages will be used within the ZF ecosystem: Expressive.
Helps identify that these packages target middleware and/or PSR-7, due to the affinity with Expressive.
Keeps our “branding”, in a way that’s been established in other ecosystems (Slim, Lumen, etc.).
While these packages will be used in the Apigility on Expressive initiative, I’ll note that the existing Apigility packages largely eschew the Apigility name as well, with the exception of those that tie the components together (zf-apigility, zf-apigility-admin, zf-apigility-provider, zf-apigility-skeleton) and those related to documentation features. Additionally, like the bulk of those packages, while these new packages will be used for Apigility applications, they can also be dropped into existing Expressive applications piecemeal. As such, naming them after Apigility seems more limiting than naming them after Expressive.
We will use both repository tags and composer keywords to signal what PSRs and affiliated projects they may target: Apigility, Expressive, PSR-7/PSR-15/PSR-17, middleware, etc. These will help users discover packages of interest.
standalone
Glad to know that tags will be used.