PHPackages                             mducharme/date-formatter - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. mducharme/date-formatter

ActiveLibrary[Utility & Helpers](/categories/utility)

mducharme/date-formatter
========================

A date formatter to easily standardize date-time values in a PHP application / API.

0.1.1(6y ago)13631MITPHPPHP ^7CI failing

Since Jun 14Pushed 6y ago1 watchersCompare

[ Source](https://github.com/mducharme/date-formatter)[ Packagist](https://packagist.org/packages/mducharme/date-formatter)[ RSS](/packages/mducharme-date-formatter/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (2)Dependencies (4)Versions (3)Used By (0)

Date Formatter
==============

[](#date-formatter)

A simple service to format a date in constant format(s) across a PHP project / API.

Table of contents
=================

[](#table-of-contents)

- [How to install](#how-to-install)
- [How to use](#how-to-use)
    - [The parser](#the-parser)
    - [The formatter](#the-formatter)
    - [The Service Provider](#the-service-provider)

How to install
==============

[](#how-to-install)

PHP 7 is required. Install with composer:

```
composer require mducharme/date-formatter
```

How to use
==========

[](#how-to-use)

Ready-to-use, with a Pimple container:

```
$container = new \Pimple\Container();
$container->register(new \Mducharme\DateFormatter\ServiceProvider());

$formatter = $container['date/formatter'];
$displayDate = $formatter->format($date);
```

With the services directly:

```
$formatter = new \Mducharme\DateFormatter\Formatter(
    new \Mducharme\DateFormatter\Parser()
);
$displayDate = $formatter->format($date);
```

The parser
----------

[](#the-parser)

In addition to the `Formatter`, a `Parser` service is also included. It has a single purpose, to ensure a mixed value, either a DateTime object or a parsable string, is parsed a DateTime object.

Any invalid string or parameter will throw an exception (`\InvalidArgumentException`) when parsing. Except null value, which are allowed by default but may be disallowed with a parameter to the `parse()` method. In thoses cases, `null` will be returned by the `parse()` method instead of a `\DateTimeInterface` object if it is allowed as a parameter.

```
use \Mducharme\DateFormatter\Parser;

$parser = new Parser();

// Setting the strict mode to false allows a parser that will not throw exceptions.
$softParser = new Parser(false);

// With proper parameters, the parser returns (parsed) Datetime objects
$parser->parse('now');

// With invalid string or types of parameter, the strict parser throws an `\InvalidArgumentException`.
$parser->parse('-invalid-');
$parser->parse(new InvalidObject());
$oarser->parse(false);
```

Handling `null`:

```
// By default, null is allowed.
// Parsing returns null in this case, instead of the usual DateTimeInterface.
$parser->parse(null);

// If null is disallowed, attempting to parse a null value also throws an `\InvalidArgumentException`.
$parser->parse(null, false);
```

As a single-purpose service, the `Parser` is also invokable and may be called directly:

```
$parsed = $parser($date);
```

The Formatter
-------------

[](#the-formatter)

The formatter is the main Service provided by this library. It has a single purpose, to render a DateTime object into a formatted string (or multiple formats).

As a single-purpose service, the `Formatter` is also invokable:

```
echo $formatter($date, 'atom');
```

It comes with many formats by default. See the [Formatter](https://github.com/mducharme/date-formatter/tree/master/src/Formatter.php) source file for details on the default format. You may get an array of all available formats by using `Formatter::ALL` as the format parameter:

```
$formatter = new Formatter($parser);
$allFormats = $formatter($date, Formatter::ALL);
var_dump($allFormats);
```

It is possible to add custom formats, or overwrite default ones, by passing an optional array of formats to the Formatter constructor.

```
$customFormats = [
    'is-leap-year' => function(\DateTimeInterface $date) {
        return ($date->format('L') ? 'Yes' : 'No';
    },
    'custom-string' => 'H:i:S (u) d-m-Y'
];
$formatter = new Formatter($parser, $customFormats);

// Outputs "Yes" because 2012 was a leap year
echo $formatter(new DateTime('2012-01-01'), 'is-leap-year');

// Outputs the custom format
echo $formatter(new DateTime('2012-01-01'), 'custom-string');
```

It is also possible to return an array of formatted dates, by specifying an array of formats:

```
$formats = $formatter('2012-01-01', ['atom', 'custom-string', 'is-leap-year']);
```

*Formats* can either be a string, which will be formatted with `DateTimeInterface::format()` or a callback function with the following signature:

```
/**
 * @param \DateTimeInterface A date object.
 * @return string
 */
function callback(\DateTimeInterface $date);
```

If no `$format` is provided to the `format()` method (2nd parameter), then the default one will be used. Setting the default format is possible with the constructor. It is optional and will default to the 'atom' format.

```
// This will use the "atom" format as no default format was specified to the constructor
$formatter1 = new Formatter($parser, null, null);
echo $formatter1($date);

// This will use the "rfc822" format, as it was set as default
$formatter2 = new Formatter($parser, null, 'rfc822');
echo $formatter2($date);
```

The Service Provider
--------------------

[](#the-service-provider)

As a convenience, a Pimple Service Provider is also included for an already bootstrapped parser (`date/parser`) and formatter (`date/formatter`).

```
$container = new \Pimple\Container();
$container->register(new \Mducharme\DateFormatter\ServiceProvider());

$parser = $container['date/parser'];
$formatter = $container['date/formatter'];
```

To customize the options, the `date/custom-formats` and `date/default-format` container options can be extended.

###  Health Score

26

—

LowBetter than 43% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity14

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 75% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~275 days

Total

2

Last Release

2254d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/cfb071c0ff7ce9500c528a003a2c53124248debc3e5bf367c17f89f5e6136125?d=identicon)[mducharme](/maintainers/mducharme)

---

Top Contributors

[![mducharme](https://avatars.githubusercontent.com/u/12157?v=4)](https://github.com/mducharme "mducharme (3 commits)")[![dominiclord](https://avatars.githubusercontent.com/u/1775204?v=4)](https://github.com/dominiclord "dominiclord (1 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/mducharme-date-formatter/health.svg)

```
[![Health](https://phpackages.com/badges/mducharme-date-formatter/health.svg)](https://phpackages.com/packages/mducharme-date-formatter)
```

###  Alternatives

[ckfinder/ckfinder-laravel-package

CKFinder 3 package for Laravel

159497.2k48](/packages/ckfinder-ckfinder-laravel-package)[jaxon-php/jaxon-core

Jaxon is an open source PHP library for easily creating Ajax web applications

73142.3k25](/packages/jaxon-php-jaxon-core)[ckfinder/ckfinder-symfony-bundle

CKFinder bundle for Symfony

42435.7k](/packages/ckfinder-ckfinder-symfony-bundle)[inpsyde/wp-app-container

DI Container and related tools to be used at website level.

41253.5k](/packages/inpsyde-wp-app-container)[rockettheme/toolbox

RocketTheme Toolbox Library

22526.9k3](/packages/rockettheme-toolbox)[rochamarcelo/cake-pimple-di

A cakephp plugin for dependency injection based on Pimple library

12176.8k](/packages/rochamarcelo-cake-pimple-di)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)