Skip to content

Commit bcbff56

Browse files
mychidarkomychidarko
committed
chore: update readme
1 parent dad8309 commit bcbff56

1 file changed

Lines changed: 177 additions & 46 deletions

File tree

‎README.md‎

Lines changed: 177 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,83 +1,214 @@
11
<!-- markdownlint-disable no-inline-html -->
22
<p align="center">
3-
<br><br>
4-
<img src="https://leafphp.dev/logo-circle.png" height="100"/>
3+
<br>
4+
<img src="https://leafphp.dev/logo-circle.png" height="120"/>
55
<br>
66
</p>
77

8-
<h1 align="center">Tick</h1>
8+
<h1 align="center">⏰ Tick</h1>
9+
10+
<p align="center">
11+
<b>A powerful, elegant date/time manipulation library for PHP with a familiar JavaScript-like API</b>
12+
</p>
913

1014
<p align="center">
11-
<a href="https://packagist.org/packages/leafs/date"
12-
><img
13-
src="https://poser.pugx.org/leafs/date/v/stable"
14-
alt="Latest Stable Version"
15-
/></a>
16-
<a href="https://packagist.org/packages/leafs/date"
17-
><img
18-
src="https://poser.pugx.org/leafs/date/downloads"
19-
alt="Total Downloads"
20-
/></a>
21-
<a href="https://packagist.org/packages/leafs/date"
22-
><img
23-
src="https://poser.pugx.org/leafs/date/license"
24-
alt="License"
25-
/></a>
15+
<a href="https://packagist.org/packages/leafs/date"><img src="https://poser.pugx.org/leafs/date/v/stable" alt="Latest Stable Version"/></a>
16+
<a href="https://packagist.org/packages/leafs/date"><img src="https://poser.pugx.org/leafs/date/downloads" alt="Total Downloads"/></a>
17+
<a href="https://packagist.org/packages/leafs/date"><img src="https://poser.pugx.org/leafs/date/license" alt="License"/></a>
2618
</p>
27-
<br />
28-
<br />
2919

30-
[Tick](https://leafphp.dev/docs/utils/date.html) is a minimalist PHP library that parses, validates, manipulates, and displays dates and times with a largely DayJS/MomentJS-compatible API. If you use DayJS, you already know how to use Tick.
20+
<!-- <p align="center">
21+
<a href="#installation">Installation</a> •
22+
<a href="#quick-start">Quick Start</a> •
23+
<a href="#features">Features</a> •
24+
<a href="#api-reference">API Reference</a> •
25+
<!-- <a href="#examples">Examples</a> •
26+
</p> -->
27+
<br>
28+
29+
## 🌟 Why Tick?
30+
31+
**Tick** is a modern, lightweight PHP date/time library designed to make working with dates and times as painless as possible. If you're familiar with JavaScript libraries like Moment.js or Day.js, you'll feel right at home with Tick.
3132

3233
```php
33-
tick()->now(); // get the current timestamp
34-
tick()->format('YYYY-MM-DD'); // format the current timestamp
35-
tick()->startOf('month')->add(1, 'day')->set('year', 2018)->format('YYYY-MM-DD HH:mm:ss');
34+
// Get current date in a specific format
35+
echo tick()->format('MMMM Do, YYYY'); // March 31st, 2025
36+
37+
// Chain methods for complex operations
38+
$nextFriday = tick()->add(1, 'week')->startOf('week')->add(4, 'day');
39+
echo $nextFriday->format('dddd, MMMM D'); // Friday, April 11
3640
```
3741

38-
## Installation
42+
## 🚀 Installation
3943

40-
You can install Tick using the [Leaf CLI](https://cli.leafphp.dev):
44+
**Using [Leaf CLI](https://cli.leafphp.dev) (Recommended)**:
4145

4246
```bash
4347
leaf install date
4448
```
4549

46-
Or with [Composer](https://getcomposer.org/):
50+
**Using [Composer](https://getcomposer.org/)**:
4751

4852
```bash
4953
composer require leafs/date
5054
```
5155

52-
## API
56+
## 🏁 Quick Start
57+
58+
```php
59+
// Current date and time
60+
echo tick()->now(); // 2025-03-31T12:29:29+00:00
61+
62+
// Parse a specific date
63+
$birthday = tick('1990-05-15');
64+
echo $birthday->format('MMMM D, YYYY'); // May 15, 1990
65+
66+
// Manipulate dates
67+
$futureDate = tick()->add(3, 'months')->subtract(2, 'days');
68+
echo $futureDate->format('YYYY-MM-DD'); // 2025-06-29
69+
```
70+
71+
## ✨ Features
5372

54-
It's easy to use Tick's APIs to parse, validate, manipulate, and display dates and times.
73+
- **🔄 Familiar API** - If you know Day.js or Moment.js, you already know Tick
74+
- **🪶 Lightweight** - No heavy dependencies, just pure PHP goodness
75+
- **⚡ Immutable & Chainable** - All operations return a new Tick instance
76+
- **🔌 Native Integration** - Seamless integration with PHP's DateTime objects
77+
- **🌐 Timezone Support** - Work with dates across different timezones effortlessly
78+
- **📊 Date Comparison** - Easily compare dates with intuitive methods
79+
- **🧩 Extensible** - Add your own custom functionality when needed
80+
- **🔍 Validation** - Validate dates with built-in methods
81+
- **📝 Formatting** - Format dates in any way you need
5582

56-
- Simple, powerful and intuitive API
83+
## 📚 API Reference
84+
85+
### Creating Dates
86+
87+
```php
88+
// Current date and time
89+
tick();
90+
tick()->now();
91+
92+
// From string
93+
tick('2025-03-31');
94+
tick('2025/03/31');
95+
tick('March 31, 2025');
96+
97+
// From DateTime
98+
tick(new DateTime('2025-03-31'));
99+
100+
// From tick object
101+
$tomorrow = tick('2025-03-31')->add(1, 'day');
102+
tick($tomorrow);
103+
```
104+
105+
### Formatting
57106

58107
```php
59-
tick('2018-08-08') // parse
60-
tick()->format('{YYYY} MM-DDTHH:mm:ss SSS [Z] A') // display
61-
tick()->set('month', 3)->month() // get & set
62-
tick()->add(1, 'year') // manipulate
63-
tick()->isBefore('...') // query
108+
$date = tick('2025-03-31');
109+
110+
// Standard formats
111+
$date->format('YYYY-MM-DD'); // 2025-03-31
112+
$date->format('MMMM D, YYYY'); // March 31, 2025
113+
$date->format('ddd, MMM D, YYYY'); // Mon, Mar 31, 2025
114+
$date->format('YYYY-MM-DD HH:mm:ss'); // 2025-03-31 12:29:29
115+
116+
// Predefined formats
117+
$date->toDateString(); // 2025-03-31
118+
$date->toTimeString(); // 12:29:29
119+
$date->toDateTimeString(); // 2025-03-31 12:29:29
120+
$date->toISOString(); // 2025-03-31T12:29:29.000Z
64121
```
65122

66-
- Full support for native PHP DateTime
123+
### Manipulating Dates
67124

68125
```php
69-
tick(new DateTime('2018-08-08')) // parse
70-
tick(new DateTime('2018-08-08'))->format('YY-MM-DD') // display
71-
tick(new DateTime('2018-08-08'))->set('month', 3)->month() // get & set
72-
tick(new DateTime('2018-08-08'))->add(1, 'year') // manipulate
73-
tick()->isBefore(new DateTime('2018-08-09')) // query
74-
tick()->toDateTime() // convert to DateTime
126+
$date = tick('2025-03-31');
127+
128+
// Add time
129+
$date->add(1, 'day'); // 2025-04-01
130+
$date->add(2, 'months'); // 2025-05-31
131+
$date->add(1, 'year'); // 2026-03-31
132+
133+
// Subtract time
134+
$date->subtract(1, 'week'); // 2025-03-24
135+
$date->subtract(3, 'hours'); // 2025-03-31 09:29:29
136+
137+
// Start/End of time units
138+
$date->startOf('month'); // 2025-03-01 00:00:00
139+
$date->endOf('year'); // 2025-12-31 23:59:59.999999
140+
$date->startOf('day'); // 2025-03-31 00:00:00
75141
```
76142

77-
- Highly recursive API
143+
### Comparing Dates
78144

79145
```php
80-
tick('2018-08-08')->isBefore(
81-
tick('2018-08-09')->add(1, 'day')->set('year', 2018)
82-
);
146+
$date = tick('2025-03-31');
147+
148+
$date->isBefore('2025-04-01'); // true
149+
$date->isAfter('2025-03-30'); // true
150+
$date->isSame('2025-03-31'); // true
151+
$date->isBetween('2025-03-30', '2025-04-01'); // true
83152
```
153+
154+
<!-- ## 🧪 Examples
155+
156+
### Working with Relative Dates
157+
158+
```php
159+
// Get tomorrow's date
160+
$tomorrow = tick()->add(1, 'day');
161+
162+
// Get the first day of next month
163+
$nextMonth = tick()->add(1, 'month')->startOf('month');
164+
165+
// Get last day of current month
166+
$lastDay = tick()->endOf('month');
167+
168+
// Check if a date is on a weekend
169+
$isWeekend = tick('2025-04-05')->day() === 0 || tick('2025-04-05')->day() === 6;
170+
``` -->
171+
172+
<!-- ### Date Calculations
173+
174+
```php
175+
// Calculate age
176+
$birthdate = tick('1990-05-15');
177+
$age = tick()->diff($birthdate, 'years');
178+
179+
// Calculate days until an event
180+
$christmas = tick('2025-12-25');
181+
$daysUntilChristmas = $christmas->diff(tick(), 'days');
182+
183+
// Calculate business days between dates
184+
$workDays = tick('2025-04-01')->diffBusinessDays(tick('2025-04-30'));
185+
``` -->
186+
187+
### Working with Timezones
188+
189+
```php
190+
// Create a date in a specific timezone
191+
$tokyoTime = tick('2025-03-31', 'Asia/Tokyo');
192+
193+
// Convert between timezones
194+
$newYorkTime = $tokyoTime->setTimezone('America/New_York');
195+
```
196+
<!--
197+
// Get timezone offset
198+
$offset = tick()->getTimezoneOffset(); // in minutes -->
199+
200+
## 🤝 Contributing
201+
202+
Contributions are welcome! Please feel free to submit a Pull Request.
203+
204+
1. Fork the repository
205+
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
206+
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
207+
4. Push to the branch (`git push origin feature/amazing-feature`)
208+
5. Open a Pull Request
209+
210+
---
211+
212+
<p align="center">
213+
Made with ❤️ by <a href="https://leafphp.dev">Leaf PHP</a>
214+
</p>

0 commit comments

Comments
 (0)