README

If you're looking for a full-featured PHP date library, I recommend Carbon.

This project is more of a utility library for recurring needs in my projects over time.

Installation

Use Composer to install the package :

composer require samuelbakon/chrono

Migration depuis DateUtil (v1.x vers v2.x)

If you're migrating from an older version that used the DateUtil class, here's how to update your code :

Old method (DateUtil) :

## Recommended Usage (Static Methods)

All Chrono methods are available statically, which is the recommended way to use the library:

```php
use SamBakon\Chrono\Chrono;

// Create and format dates
$date = Chrono::getDate('2023-06-15');
$formatted = Chrono::getDateAsString($date, 'Y-m-d');

// Date calculations
$newDate = Chrono::addDaysToDate($date, 5);
$diff = Chrono::getDateDayDif($date1, $date2);

// Date ranges
$dates = Chrono::getDatesFromRange('2023-06-01', '2023-06-15');

Alternative (Instance Methods)

While static usage is preferred, you can also create an instance of Chrono if needed:

use SamBakon\Chrono\Chrono;

$chrono = new Chrono();
$date = $chrono->getDate('2023-06-15');
$formatted = $chrono->getDateAsString($date, 'Y-m-d');

Main changes :

Methods have been distributed into specialized classes :
- ChronoComputer : Math operations on dates
- ChronoCalendar : Calendar operations
- ChronoPeriod : Interval management
- ChronoCasting : Conversion and formatting
Better method name consistency and return types
Better error handling and edge case management
More complete documentation and updated examples

Usage

Basic usage

All functionalities are available through static methods of the Chrono class:

use SamBakon\Chrono\Chrono;

// Create a date
$date = Chrono::getDate('2023-06-15 14:30:00');

// Add days to a date
$newDate = Chrono::addDaysToDate($date, 5);
echo $newDate->format('Y-m-d H:i:s'); // 2023-06-20 14:30:00

// Calculer la différence en minutes entre deux dates
$date1 = new DateTime('2023-06-15 10:00:00');
$date2 = new DateTime('2023-06-15 14:30:00');
$minutesDiff = ChronoComputer::getMinuteDateDif($date1, $date2);
echo "Différence: $minutesDiff minutes"; // 270 minutes

// Convertir des unités de temps
$hours = ChronoComputer::convertMinutesToHours(90); // 1.5
$minutes = ChronoComputer::convertHoursToMinutes(2); // 120

// Obtenir le temps écoulé depuis une date (format lisible)
$lastSeen = new DateTime('2023-06-10 14:30:00');
echo ChronoComputer::lastSeenHelp($lastSeen); // "3 Days" (if today is 13/06/2023)

Calendar operations

// Get the first day of the week for a given date
$date = Chrono::getDate('2023-06-15'); // A Thursday
$monday = Chrono::getFirstDayOfTheWeekFromDate($date);
echo $monday->format('Y-m-d'); // 2023-06-12 (Monday)

// Formater une date
$formattedDate = ChronoCalendar::formatDateDay($date);
echo $formattedDate; // 15/06/2023

// Obtenir le jour de la semaine
$dayOfWeek = ChronoCalendar::getDayOfWeek($date);
echo $dayOfWeek; // "THURSDAY"

// Obtenir le nom du mois à partir de sa position
echo ChronoCalendar::getMonthFromPosition(6); // "JUN"

Interval management

// Get the interval of today (from midnight to 23:59:59)
$today = Chrono::getIntervalOfToday();
$start = $today['start']->format('Y-m-d H:i:s');
$end = $today['end']->format('Y-m-d H:i:s');
echo "Today from $start to $end";

// Get all dates between two dates
$startDate = '2023-06-01';
$endDate = '2023-06-03';
$dates = ChronoPeriod::getDatesFromRange($startDate, $endDate);
// Returns ['2023-06-01', '2023-06-02', '2023-06-03']

// Ajuster un intervalle de dates
$interval = ChronoPeriod::adjustFilterInterval(
    new DateTime('2023-06-01'),
    new DateTime('2023-06-15')
);

Conversion and formatting

// Convert a timestamp to a DateTime object
$date = Chrono::timeToDate(1686844800);
echo $date->format('Y-m-d'); // 2023-06-15

// Create a DateTime object from a string
$date = Chrono::getDate('2023-06-15');

// Format a date
$formatted = Chrono::getDateAsString($date, 'Y/m/d');
echo $formatted; // 2023/06/15

// Check if a date is valid
$isValid = ChronoCasting::isValidDate('2023-12-31'); // true

// Convert an abbreviated day to its full name
$fullDay = ChronoCasting::parseDay('Mon'); // "Monday"

Main features

ChronoComputer: Date calculations and mathematical operations
ChronoCalendar: Calendar operations (weeks, months, years)
ChronoPeriod: Interval management and date ranges
ChronoCasting: Conversion between formats and typing of dates
Compatible with native PHP DateTime objects
Strict typing and complete documentation
High test coverage
Respect of PSR-12 code standards

Configuration requirements

PHP 7.4 or higher
PHP DateTime extension enabled

Licence

This project is under the MIT license. See the LICENSE file for more details.

API Documentation

For a complete documentation of all methods, consult the source code or generate PHPDoc documentation.

Contribution

Contributions are welcome! Before submitting a pull request, please :

Create an issue to discuss the proposed change
Create a branch for your feature (feature/my-new-feature)
Run the tests and make sure they pass
```
composer test
```

Check the code quality :

# Check code style
composer check-style

# Run static analysis
composer static-analysis

# Check code coverage (must be > 80%)
composer test-coverage

Update the documentation if necessary
Submit a pull request

Development environment

To configure your development environment :

Clone the repository :

git clone https://github.com/yourusername/Chrono.git
cd Chrono

Install dependencies :
```
composer install
```
Run tests :
```
composer test
```

Changelog

Consult the CHANGELOG.md for a list of recent changes.

Development

Run tests

composer test

Check code quality

composer check-style
composer static-analysis

Author

Samuel Bakon (Samy)

Developed with ❤️ And 🤖

sambakon / chrono

Maintainers

Details