programster / core-libs
Core libraries for PHP 8.3+
Requires
- php: ^8.3
- ext-fileinfo: *
- ext-sodium: *
Requires (Dev)
None
Suggests
- ext-curl: Facilitates downloads through curl instead of falling back to using file_get_contents.
- ext-mbstring: Allows the use of Filesystem::convertFileToUtf8().
- ext-openssl: Allows the use of Network::getPublicIp(), which uses HTTPS, and EncryptionLib::decryptLegacy().
- ext-posix: Allows File and Directory moves to another filesystem to check that owners and groups can be kept (needed with the default PreserveOwnershipEnum::YES).
- ext-sockets: Allows the use of the networking methods that require sockets.
- ext-zip: Allows the use of methods that assist with using zip file.
Provides
None
Conflicts
None
Replaces
None
- dev-master
- 3.0.0
- 3.0.0-alpha.2
- 3.0.0-alpha.1
- 2.6.5
- 2.6.4
- 2.6.3
- 2.6.2
- 2.6.1
- 2.6.0
- 2.5.5
- 2.5.4
- 2.5.3
- 2.5.2
- 2.5.1
- 2.5.0
- 2.4.0
- 2.3.6
- 2.3.5
- 2.3.4
- 2.3.3
- 2.3.3.b
- 2.3.3a
- 2.3.2
- 2.3.1
- 2.3.0
- 2.2.0
- 2.1.2
- 2.1.1
- 2.1.0
- 2.0.1
- 2.0.0
- 1.7.10
- 1.7.9
- 1.7.8
- 1.7.7
- 1.7.6
- 1.7.5
- 1.7.4
- 1.7.3
- 1.7.2
- 1.7.1
- 1.7.0
- 1.6.x-dev
- 1.6.3
- 1.6.2
- 1.6.1
- 1.6.0
- 1.5.0
- 1.4.1
- 1.4.0
- 1.3.0
- 1.2.1
- 1.2.0
- 1.1.45
- 1.1.44
- 1.1.43
- 1.1.42
- 1.1.41
- 1.1.40
- 1.1.39
- 1.1.38
- 1.1.37
- 1.1.36
- 1.1.35
- 1.1.34
- 1.1.33
- 1.1.32
- 1.1.31
- 1.1.30
- 1.1.29
- 1.1.28
- 1.1.27
- 1.1.26
- 1.1.25
- 1.1.24
- 1.1.23
- 1.1.22
- 1.1.21
- 1.1.20
- 1.1.19
- 1.1.18
- 1.1.17
- 1.1.16
- 1.1.15
- 1.1.14
- 1.1.13
- 1.1.12
- 1.1.11
- 1.1.10
- 1.1.9
- 1.1.8
- 1.1.7
- 1.1.6
- 1.1.5
- 1.1.4
- 1.1.3
- 1.1.2
- 1.1.1
- 1.1.0
- 1.0.1
- 1.0.0
- dev-pre-php-8.5
- dev-pre-8.3
- dev-temp
This package is auto-updated.
Last update: 2026-11-14 09:05:09 UTC
README
Contents
- About
- Requirements
- Installation
- Quick start
- What's in it
- Documentation
- Upgrading from version 2
- Arrays (
ArrayLib) - Strings (
StringLib) - System, processes and web requests (
Core) - Command line scripts (
CliLib) - CSV files (
CsvLibandCsvFile) - Files and directories (
Filesystem) - Changing files safely
- Moving and renaming (
File,Directory) - Networking (
Network) - Encryption and passwords (
EncryptionLib) - Exceptions
- Supported platforms (Linux, macOS, Windows, WSL)
- Testing
- Design principles
- License
About
This is a PHP package of static libraries that "extend" the standard library, with the things that PHP projects keep needing but PHP doesn't quite provide: reading and rewriting huge CSV files without running out of memory, deleting or moving a directory tree safely, getting the system's memory, running a shell command that throws when it fails, and so on. It is built primarily for rapid development and ease of understanding, rather than raw performance.
Requirements
- PHP 8.3 or a later version of PHP 8 (8.3, 8.4 and 8.5 are tested). Where PHP 8.5 has a native function for something, it is used.
- The
fileinfoandsodiumextensions, which most PHP installs already have.
Linux has first-class support, and macOS, Windows and WSL are tested too. See Supported platforms for the few things that differ.
Installation
composer require programster/core-libs
Then use the classes from the Programster\CoreLibs namespace:
use Programster\CoreLibs\Filesystem; $size = Filesystem::getDirSize("/var/log");
Optional extensions
Some methods need an extension that the package doesn't require, so that you can install it without them if you don't
use those methods. If one is missing, the method throws a MissingExtensionException saying which extension it needs,
rather than failing in some less obvious way.
| Extension | Needed by |
|---|---|
mbstring |
Filesystem::convertFileToUtf8() |
zip |
Filesystem::zipDir() and Filesystem::unzip() |
sockets |
Network::sendTcpRequest() |
openssl |
Network::getPublicIp() (which uses HTTPS), and EncryptionLib::decryptLegacy() |
posix |
File and Directory moves to another filesystem with PreserveOwnershipEnum::YES (the default), to check who owns what |
curl |
Nothing: Filesystem::downloadFile() uses it if it is there, and PHP's own HTTP support otherwise |
Quick start
use Programster\CoreLibs\Core; use Programster\CoreLibs\CsvLib; use Programster\CoreLibs\Enums\DataSizeUnitEnum; use Programster\CoreLibs\Enums\MemoryTypeEnum; use Programster\CoreLibs\Filesystem; use Programster\CoreLibs\Models\Directory; // Run a command, getting an exception (with its exit code and error output) if it fails. $branch = trim(Core::runCommand("git rev-parse --abbrev-ref HEAD")); // How much memory is available, in GiB. $available = Core::getMemory(MemoryTypeEnum::AVAILABLE, DataSizeUnitEnum::GIB); // Strip the whitespace from every value of a CSV file, one row at a time, however big it is. CsvLib::trim("/data/export.csv"); // Move a directory to another disk, keeping its owners and permissions, and its symlinks working. $uploads = new Directory("/srv/uploads"); $uploads->move("/mnt/archive"); // Delete a directory tree. Everything is checked first, so either all of it goes, or none of it does. Filesystem::deleteDir("/tmp/build");
What's in it
| Class | For |
|---|---|
ArrayLib |
Getting the first, last or a random element or key, fast diffs and intersections, splitting an array evenly, merging with a clash handler |
StringLib |
Random strings, startsWith()/endsWith()/contains() with case options, line breaks and <br> tags, URL-safe base64 |
Core |
Running commands, memory and processor counts, process titles, request arguments, safe redirects, signed data, the clipboard |
CliLib |
Progress bars, and reading a password without showing it |
CsvLib, CsvFile |
Validating, converting, trimming, merging and comparing CSV files, and removing their rows or columns |
Filesystem |
Listing, creating, deleting, zipping and sizing directories, filtering and converting files, paths, downloads |
File, Directory |
Moving and renaming, including across filesystems, with progress, cancelling and resuming |
Network |
IP addresses, open ports, simple TCP requests, and the current web request (whether it is HTTPS, and its URL) |
EncryptionLib |
Authenticated encryption, and password hashing |
Documentation
The docs folder has a page for each area, with examples, and the details that are easy to be caught out by.
Every public method also has a full docblock, which your IDE will show, saying what it does, what each parameter means,
and every exception it can throw.
If you are upgrading from version 2, start with Upgrading from version 2, as version 3 has
breaking changes, some of which (e.g. Filesystem::mkdir() no longer creating parent directories by default) won't
show up as errors.
Design principles
These apply throughout, so are worth knowing before you start:
- Failures throw. Methods throw an exception if something goes wrong, rather than returning
falseornullfor you to check. Every exception the library throws extendsCoreLibsException, so you can catch them all at once. See Exceptions. - Safe by default. Where a method could do something surprising or dangerous, the default is the safe choice, and
the riskier behaviour needs an extra parameter. For example,
Core::redirectUser()won't redirect to another site unless you pass$allowExternal,Filesystem::unzip()refuses a zip with symlinks pointing outside it unless you pass$trusted, andFilesystem::deleteDir()won't follow symlinks unless you pass$followSymlinks. - Nothing half done. Methods that change files check everything they can before changing anything, and write new contents to a temporary file before replacing the original, so a failure part way through leaves things as they were. See Changing files safely.
- Big files are fine. The CSV and file methods work a row or line at a time, so the size of the file doesn't matter.
CsvLib::convertCsvToArray()(andCsvFile::toArray()) is the exception, as it returns everything as an array. - Every class is
final, and the libraries only have static methods.
License
MIT. See LICENSE.