Jan Mikoláš
Glossary
Library
A library provides reusable functionality that an application calls directly. A package is a means of distribution, while a framework controls application flow—these concepts often overlap, but they are not identical.
Short definition
Usable code with its own public contract.
A library may provide an HTTP client, UUID handling, logging, validation, or testing. Its public API is an agreement with the application: it defines available classes, methods, data types, exceptions, and compatibility rules.
In PHP, libraries are commonly distributed as Composer packages and loaded through a PSR-4 autoloader. However, a package may also contain a CLI tool, plugin, or framework component, so package and library are not exact synonyms.
The problem it solves
It avoids solving the same technical task repeatedly
A good library provides a maintained contract for a problem that custom code would otherwise solve repeatedly or less effectively.
- an HTTP client for an external API
- logging and correlation identifiers
- working with UUIDs, time, or a data format
- validation, serialisation, or cryptographic functions
- testing frameworks and static-analysis tools
Practical example
Composer exposes a declared library through the autoloader
A PHP application declares a dependency in composer.json. Composer resolves its version, including transitive dependencies, records the state in composer.lock, and creates an autoloader. The application then works only with the library’s public API.
Loading the autoloader itself is neither a security check nor a guarantee of compatibility. A library change should be reviewed together with its version, changelog, tests, and impact on the application.
require __DIR__ . '/vendor/autoload.php';
// Aplikace používá veřejné API nainstalované knihovny.How it works
The application calls a contract; the library hides its implementation
Text diagram: application → library’s public API → internal implementation → result or exception.
- Choosing a solution The team evaluates whether a small custom implementation or an external library is more suitable in the long term.
- Declaring the dependency The package is added to Composer with a supported version and platform requirements.
- Installation and autoloading Composer installs locked versions and creates class mappings.
- Using the public API The application calls the documented contract, not internal classes that may change.
- Maintenance Updates are controlled and accompanied by tests and an assessment of compatibility and security implications.
Important concepts
Public contract, versions, and dependencies.
The value of a library depends on the stability of its contract and the ability to maintain it safely.
Public API
Classes, functions, interfaces, and exceptions intended for library users. Internal parts should not become an unofficial application foundation.
Package and dependencies
A package is a distribution unit and may have its own direct and transitive dependencies. Each expands the maintenance and security surface.
Versioning
Semantic versioning helps describe compatibility, but it is not an absolute guarantee. Every change still needs verification in the application context.
Autoloading
PSR-4 maps namespaces to directories and avoids manually requiring individual classes.
Documentation and licence
Before adoption, assess support, security, licensing, maintenance activity, and the clarity of documentation.
Benefits and limitations
Reuse saves code but adds a dependency.
Benefits
- proven functionality for a recurring technical problem
- clearer interfaces between parts of the code
- shared maintenance and fixes across several projects
- standard installation through a dependency manager
Common mistakes
- adding a package for a trivial function without maintenance value
- calling undocumented internal library classes
- updating dependencies blindly without tests
- assuming a small or popular library is automatically secure
When it makes sense
When a library solves a genuine recurring problem better than custom code.
A library is suitable for standard HTTP communication, cryptography, validation, or testing, for example, where well-known behaviour and maintenance matter. For a short local transformation, a simple, tested custom implementation may instead be clearer.
The decision is not only about the number of lines. It also involves licensing, supported PHP versions, security updates, system compatibility, and the team’s ability to maintain dependency changes.
What to consider
Every dependency is part of the product.
Libraries live as long as the code built on them.
- assess the public API, maintenance activity, licence, and supported platforms
- keep an application’s lock file in version control
- update dependencies in smaller, manageable changes
- run tests and security checks after dependency changes
- do not use internal implementation details as an undocumented contract
Common questions
Libraries without confusion
Is every Composer package a library?
No. A package may contain a library, framework, CLI tool, plugin, or other distributable software.
How does a library differ from a framework?
An application usually calls a library. A framework controls the main flow and calls application code at a defined time.
Why commit composer.lock?
For an application, it records a specific dependency set so CI and production install the same verified state.
When should I write a small custom implementation?
When the problem is narrowly scoped and an external dependency would add more maintenance than simple, verifiable code.
How I work with PHP in practice
I select dependencies as part of a backend maintained for the long term.
In PHP projects, I combine framework components, integration libraries, and quality gates so their impact remains clear and verifiable.