Download the PHP package liturgical-calendar/components without Composer

On this page you can find all versions of the php package liturgical-calendar/components. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package components

CodeFactor php version Packagist Packagist stats

Stato traduzione ApiOptions

Stato traduzione WebCalendar

Liturgical Calendar Components for PHP

A collection of reusable frontend components, that work with the Liturgical Calendar API (currently hosted at https://litcal.johnromanodorazio.com/api/dev/).

Installing the package

Installing the package in your project is as simple as composer require liturgical-calendar/components. Include in your project's PHP script with include_once 'vendor/autoload.php'; (adjust the path to vendor/autoload.php accordingly).

Note that this package requires PHP >= 8.2. It uses Enums, introduced in 8.1, but WebCalendar\Column composes one enum case from the values of others, which 8.1 rejects with "Enum case value must be compile-time evaluatable". The constraint said 8.1 until CI began checking every version and found that the package had never actually parsed there. It also requires PHP ext-intl. To check if you have all the requirements you can run composer check-platform-reqs --no-dev.

Contributing requires PHP >= 8.4.1, which is a higher bar than using the package. composer.lock pins development tooling β€” PHPUnit 12, and symfony/var-exporter by way of symfony/cache β€” that requires 8.4, so composer install cannot resolve below it. Consumers are unaffected: composer require reads only the runtime require section and never this lock. If you intend on contributing and installing development requirements, run composer check-platform-reqs.

Quick Start

The recommended way to use this library is through the ApiClient singleton, which provides a centralized configuration point for all API interactions.

Fetching Calendar Data

Building Interactive Forms

Complete Production Example

For comprehensive documentation on caching, logging, retry logic, and circuit breakers, see UPGRADE.md.

New: PSR-Compliant HTTP Features

This library now supports PSR-7 (HTTP Messages), PSR-17 (HTTP Factories), PSR-18 (HTTP Client), PSR-3 (Logging), and PSR-16 (Simple Cache) standards, providing professional-grade features:

Quick Start with Production Features

Good News: All PSR features are 100% backward compatible. Your existing code continues to work without any modifications!

For comprehensive documentation, migration examples, and performance tuning, see UPGRADE.md.

MetadataProvider - Centralized Metadata Management

Starting from version 2.x, the library uses a centralized MetadataProvider singleton for all calendar metadata operations.

Key Features

Basic Usage

Static Validation Methods

Production Setup Example

For complete documentation, see UPGRADE.md - MetadataProvider Architecture.

CalendarSelect

Produces an HTML \<select> element with \<option>s that are populated with data from the Liturgical Calendar API /calendars route. Can be instantiated passing in an array of options with the following keys:

[!CAUTION] When setOptions is set to OptionsType::DIOCESES_FOR_NATION, the nationFilter option MUST also be set, otherwise an exception will occur.

To produce the \<select> element, call the ->getSelect() method on the CalendarSelect instance.

Example:

The options can also be set by using the methods of the same name after instantiating the CalendarSelect instance, rather than passing them into the constructor. These methods allow for chaining.

Example:

[!CAUTION] When using the ->setOptions() method with a value of OptionsType::DIOCESES_FOR_NATION, the ->nationFilter() method MUST be called BEFORE calling the ->setOptions() method, otherwise an exception will occur.

RiteSelect

Produces an HTML \<select> element with one \<option> per liturgical rite. Unlike CalendarSelect it makes no API request: the set of rites comes from the Rite enum, because it is a fact about the liturgy rather than about which calendars a given API serves. Can be instantiated passing in an array of options with the following keys:

To produce the \<select> element, call the ->getSelect() method, or simply echo the instance.

[!IMPORTANT] There is no linking method, and this is deliberate. liturgy-components-js offers linkToRiteSelect(), but that is a runtime DOM listener with no server-side analogue: this library renders once and ships no JavaScript. Reacting to a rite change is the integrator's business β€” a form submit, a query parameter, or a re-render with the rite set on the CalendarSelect:

Anything interactive belongs in liturgy-components-js.

Set the same rite on the request that fetches the data, or the selection has nowhere to go:

The API routes a rite as a bare segment named by the rite itself, between calendar and any nation or diocese pair β€” /calendar/ambrosian/diocese/lugano_ch/2026. There is no /calendar/rite/{rite} spelling, and an Ambrosian diocese without the prefix is a 400: /calendar/diocese/lugano_ch is not a route.

rite() accepts a Rite case or its string value, and throws on an unknown one exactly as the two select components do. It emits the segment for whichever rite you set, roman included β€” /calendar/roman/2026 and /calendar/2026 serve the same calendar, and a request built from a RiteSelect knows its rite explicitly, so it says so. Leave the rite unset and the URL keeps its historic prefix-free shape.

Asking for a nation under a rite that has no national tier throws an InvalidArgumentException, in whichever order you set the two:

The Ambrosian rite is the rite of a handful of sees in Lombardy and Ticino with nothing above them, so /calendar/ambrosian/nation/CH is not a route and never will be. CalendarSelect expresses the same fact by skipping the national pass entirely; here it is an exception, raised where the mistake is made rather than arriving later as a 400 from get(). Dioceses are unaffected β€” they are the whole point of the rite.

ApiOptions

Produces a number of HTML \<select> elements, with \<option>s that correspond to the values of parameters that can be sent in a request to the Liturgical Calendar API /calendar route. The only \<select> element with options that are populated from the Liturgical API /calendars route is that of the locale parameter, with current supported language locales.

To produce the \<select> elements, call the ->getForm() method on the ApiOptions instance. Here is an example of the most basic usage:

Output:

Differentiate parameters according to API path

The \<select> elements that are output can be differentiated between those that correspond to parameters that can be sent on any path of the /calendar/* route (therefore for any Liturgical Calendar requested whether General Roman, national or diocesan), and those that only make sense on the base /calendar route (therefore only for the General Roman calendar). To differentiate the output, pass in the PathType enum with one of the two possible enum values:

The output will be similar to the previous output, with a <br> separating the locale, year_type, and accept header \<select> elements from the other \<select> elements.

Set locale for language names and display values

We can change the locale for the ApiOptions component, which will affect:

The locale select will now look like this:

Set a wrapper and a label

We can optionally set a \<form> or \<div> wrapper around the whole of the output, and we can also set the class and id of the wrapper element, and we can also set a label for the form (which will be included within the wrapper element):

Set a common wrapper element for each of the form select inputs

The ApiOptions component allows for fine grained control via a number of methods.

For example we can set a common wrapper element that will be wrapped around each of the form select elements, via the Input::setGlobalWrapper() and Input::setGlobalWrapperClass() methods. We can also set a common class to be used on all of the form select elements, via the Input::setGlobalInputClass() method.

[!NOTE] Other than setting the as html element as a string value in the wrapper option, or enabling the wrapper with a boolean value, we can also set wrapper to an associative array with the desired options. The following three examples are equivalent:

[!NOTE] Other than setting the as html element as a string value in the formLabel option, or enabling the formLabel with a boolean value, we can also set formLabel to an associative array with the desired options. The following three examples are equivalent:

Output:

Fine grain control of single form inputs

Usually we would want to have the same wrapper and wrapper classes and element classes on all of the form inputs. However, if we do need for any reason to have finer grained control on a specific element, say for example we would like to set an id attribute on a specific element, we can do so by targeting the relative input. The inputs are available on the ApiOptions instance as the following properties.

These render as \<select> elements:

And this one renders as an \<input type="number">:

Each of these has it's own ->class(), ->id(), ->labelClass(), ->wrapper(), ->wrapperClass(), ->disabled() and ->selectedValue() methods. If a global input wrapper or input class is also set, the single input's fine-grained methods will override the global settings for the specific input instance.

Output:

Setting the earliest selectable year on the Year input

The yearInput renders as a <input type="number"> with min="1970" β€” the first year the API will compute for the Roman rite β€” and max="9999". The floor is not the same for every rite: the Ambrosian rite is computed from 1976, the first year of the reformed Ambrosian Missal, and a request for an earlier year is refused by the API.

Rather than restate that year at the call site, tell ApiOptions which rite the form is for and let the input read the floor off it. This is the rite option, and it takes the same values as CalendarSelect's option of the same name β€” so a single options array can configure both:

The rite defaults to Roman, so an options array that never mentions one renders exactly what it always did.

The same floor can be set on the input directly, which is what the option does under the hood:

Output:

Both the option and ->rite() accept a Rite case or its string value ('roman', 'ambrosian'), and throw on any other string. Setting the Roman rite puts the floor back to 1970, so the input can be re-pointed as often as the rite changes β€” the last call wins.

Raising the floor also raises a selected year that sits below it, provided that year is one the API serves at all. A form that submitted 1970 under the Roman rite and is then re-rendered under the Ambrosian re-renders with 1976, rather than round-tripping a year the API would reject:

Clamping applies only to a selected year that is a whole number within 1970–9999. Anything else β€” a year outside that range, a fractional value, a non-numeric string β€” is not a year the API serves, so it falls back to the current year rather than being clamped, exactly as it did before the floor existed.

To set the floor to something the rite does not dictate β€” an archive that begins later than the API does, say β€” use ->min() directly. It takes any year the API serves, and throws for anything outside 1970–9999:

Updating the options for the Locale input

The default options for the Locale \<select> input are the locales supported by the API for the General Roman Calendar. However, national calendars and diocesan calendars have their own set of supported locales. In order to set the options to those supported by a given national or diocesan calendar, we can use the ->setOptionsForCalendar(string $category, string $calendar_id) method, where $category has a value of either nation or diocese, and $calendar_id corresponds to the calendar_id property of the national or diocesan calendar.

Example:

We can then set the default selected value for the localeInput based on the calendar response, using the settings->locale property from the calendar response:

Disabling inputs and setting default selected values

We can set the default selected value on the inputs as well as disable them. For example, after requesting a national or diocesan calendar, we might want to disable the ApiOptions inputs seeing that can't send any other value than those that are determined by the requested calendar. And we might want to set their default selected options to those of the requested calendar.

If no national or diocesan calendar was requested, but only the General Roman Calendar, then the inputs won't be disabled, their default selected values however will be set to those that were requested for the Calendar instance.

WebCalendar

A WebCalendar is instantiated with a response object from the Liturgical Calendar API. It does not currently take care of making the request, the request must first be sent to the API and the response must be transformed into an object, and passed in to the WebCalendar constructor.

CSS classes

Most of the table styling should be handled with CSS styling rules.

To this end, a number of CSS classes are created by default in the resulting table.

[!NOTE] The WebCalendar component currently suppresses the grade_display for celebrations of rank 7, since it is more explanatory than actually useful for display in a web calendar, having a value along the lines of 'celebration with precedence over solemnities'.

Chainable methods

The WebCalendar instance also has a number of methods that allow to further adjust and customize the layout of the calendar. These methods allow for chaining, making it easy to call them one after the other:

Non chainable methods

There are a few methods that return a value, and therefore do not allow for chaining, because they do not return the instance but rather a value.

Examples

An /examples folder has been included in the repo to allow for easy testing. Currently there is a /examples/webcalendar subfolder with an example of usage of the WebCalendar component. To quickly test locally:

Then navigate to http://localhost:3000 in your browser. You should see a form with ApiOptions and CalendarSelect. Click on Submit to see the actual web calendar.

If you would like to test against the remote instance of the API, without spawning a local instance on port 8000 or similar, then you must set the values of API_PROTOCOL, API_HOST and API_PORT in the .env.local file to those of the remote instance. Note however that as long as APP_ENV is set to development, the /examples/webcalendar example will use your local API instance instead of the remote production API. For more information on spawning a local instance of the API, see the Liturgical Calendar API Readme - testing locally.

Tests

The package includes a few unit tests to ensure that the component is working as expected. In order to run the tests, clone the package repository locally and install the dev dependencies:

Then run the composer test script, which calls the included PHPUnit package to run the tests in the tests folder.

To run a single test class or a single method within a class, use the composer test-filter script followed by the desired Class or Class::method, e.g. composer test-filter CalendarSelectTest::testIsValidLocale.

Code Quality & Linting

This project maintains high code quality standards with automated linting and static analysis.

PHP Code Quality

Markdown Linting

This project enforces consistent markdown formatting. To lint markdown files:

See MARKDOWN_LINTING.md for detailed markdown linting documentation.

Git Hooks (CaptainHook)

The project uses CaptainHook to automatically run quality checks before commits and pushes:

Pre-commit (runs on git commit):

Pre-push (runs on git push):

Hooks are automatically installed via Composer. To manually reinstall:

Translations

The few translatable strings in the component are handled via weblate. Click on the following badges to contribute to the translations.

How a locale is resolved

Two things have to be true for a component to render in the locale you asked for, and the library now handles both.

The requested locale has to name a locale the system actually has. A region-less locale is expanded through CLDR likely subtags, so en becomes en_US, pt becomes pt_BR and la becomes la_VA, tried as .utf8, .UTF-8 and bare before falling back to the language on its own. An explicit region is never overridden β€” pt_PT stays Portuguese-of-Portugal. This replaces a guess that built the region by uppercasing the language: it β†’ it_IT was right by luck, but en β†’ en_EN is not a locale on any system, so setlocale() failed and the component silently rendered in whatever locale the host process already held.

LANGUAGE has to agree. glibc's gettext reads the LANGUAGE environment variable above LC_MESSAGES, so a host that exports it overrides every locale the library sets, and LANGUAGE=C disables catalog lookup entirely. The components now pin LANGUAGE alongside the locale category. CalendarSelect, RiteSelect and WebCalendar restore both afterwards β€” the library runs inside your process and puts back exactly what it found, including a LANGUAGE you never set.

[!NOTE] ApiOptions is the exception: its inputs translate when they render, not when they are constructed, so it sets the locale and LANGUAGE and leaves them set. That is long-standing behaviour, not new β€” but if you render an ApiOptions form and then rely on the process locale for your own output, set it again afterwards.

This mirrors LocaleConfigurator in the API, which solved the same problem first.

ApiOptions translations

Stato traduzione

Stato traduzione

WebCalendar translations

Stato traduzione

Stato traduzione


All versions of components with dependencies

PHP Build Version
Package Version
Requires php Version >=8.2
ext-intl Version *
ext-json Version *
vlucas/phpdotenv Version ^5.6
psr/http-client Version ^1.0
psr/http-factory Version ^1.0
psr/http-message Version ^1.0 || ^2.0
psr/log Version ^3.0
psr/cache Version ^3.0
psr/simple-cache Version ^3.0
nyholm/psr7 Version ^1.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package liturgical-calendar/components contains the following files

Loading the files please wait ...