Skip to content

Commit b272d30

Browse files
shahruslanshahruslan
committed
Документация
1 parent 247d612 commit b272d30

File tree

3 files changed

+230
-4
lines changed

3 files changed

+230
-4
lines changed

‎README.md

+201
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# Production calendar
2+
3+
## Описание:
4+
5+
Библиотека production-calendar позволяет получать данные о производственном календаре из сервиса
6+
[production-calendar.ru](https://production-calendar.ru/).
7+
8+
## Использование:
9+
10+
Чтобы использовать библиотеку, необходимо установить её с помощью Composer:
11+
```php
12+
composer require shahruslan/production-calendar
13+
```
14+
Далее надо будет подключить какой-нибудь PSR-18 совместимый
15+
[http-client](https://packagist.org/providers/psr/http-client-implementation). Этот клиент подключается автоматически,
16+
но при желании вы можете его сконфигурировать и передать в конструктор. И в заключении получаем
17+
[токен](https://production-calendar.ru/token) для работы с API. Чтобы его получить, достаточно указать свой email, на
18+
который придет письмо с токеном. Затем можно использовать класс `Calendar` для получения данных о производственном
19+
календаре:
20+
```php
21+
use Shahruslan\ProductionCalendar\Calendar;
22+
23+
$calendar = new Calendar('your-token');
24+
25+
// Получение календаря на весь год
26+
$calendarForYear = $calendar->getPeriodForYear(2024);
27+
28+
// Получение календаря на определённый месяц
29+
$calendarForMonth = $calendar->getPeriodForMonth(2024, 1);
30+
31+
// Получение календаря на определённый день
32+
$calendarForDay = $calendar->getPeriodForDay(new DateTime('2024-01-01'));
33+
```
34+
35+
### Методы класса `Calendar`
36+
37+
- `getPeriodForYear(int $year): Period` - Получение календаря на весь год;
38+
- `getPeriodForQuarter(int $year, int $quarter): Period` - Получение календаря на определённый квартал;
39+
- `getPeriodForMonth(int $year, int $month): Period` - Получение календаря на определённый месяц;
40+
- `getPeriodForDay(DateTimeInterface $date): Period` - Получение календаря на определённый день;
41+
- `getPeriod(string $period): Period` - Получение календаря на произвольный период(не более года).
42+
43+
Каждый метод возвращает объект класса `Period`, содержащий данные о производственном календаре.
44+
45+
### Класс `Period`
46+
47+
Класс `Period` представляет собой объект, содержащий данные о производственном календаре. В свойстве `days` массив
48+
объектов типа `Day` со свойствами:
49+
- `date` - текущий день;
50+
- `type` - тип дня(праздничный, рабочий, выходной и тд);
51+
- `weekDay` - день недели;
52+
- `workingHours` - количество рабочих часов.
53+
54+
Свойство `statistic` отображает ряд статистических данных для задаваемого периода:
55+
- `calendarDays` – количество календарных дней в периоде;
56+
- `calendarDaysWithoutHolidays` - количество календарных дней в периоде без учета праздничных дней (полезный показатель
57+
для расчета продолжительности отпуска работника);
58+
- `workDays` – количество рабочих дней в периоде;
59+
- `weekends` – количество выходных дней в периоде (без учета праздничных);
60+
- `holidays` – количество праздничных дней в периоде;
61+
- `workingHours` – количество рабочего времени за период.
62+
63+
```php
64+
use Shahruslan\ProductionCalendar\Calendar;
65+
66+
$calendar = new Calendar('your-token');
67+
$period = $calendar->getPeriod('08.01.2024-10.01.2024', region: 23);
68+
print_r($period);
69+
```
70+
Output:
71+
```
72+
Shahruslan\ProductionCalendar\Entity\Period Object
73+
(
74+
[country] => Shahruslan\ProductionCalendar\Entity\Dictionary\Country Object
75+
(
76+
[code] => ru
77+
[text] => Российская Федерация
78+
)
79+
[region] => Shahruslan\ProductionCalendar\Entity\Dictionary\Region Object
80+
(
81+
[number] => 23
82+
[text] => Краснодарский край
83+
)
84+
[dateStart] => DateTimeImmutable Object
85+
(
86+
[date] => 2024-01-07 00:00:00.000000
87+
[timezone_type] => 3
88+
[timezone] => UTC
89+
)
90+
[dateEnd] => DateTimeImmutable Object
91+
(
92+
[date] => 2024-01-09 00:00:00.000000
93+
[timezone_type] => 3
94+
[timezone] => UTC
95+
)
96+
[workWeekType] => 5-и дневная рабочая неделя
97+
[period] => Произвольный период
98+
[days] => Array
99+
(
100+
[0] => Shahruslan\ProductionCalendar\Entity\Day Object
101+
(
102+
[date] => DateTimeImmutable Object
103+
(
104+
[date] => 2024-01-07 00:00:00.000000
105+
[timezone_type] => 3
106+
[timezone] => UTC
107+
)
108+
[type] => Shahruslan\ProductionCalendar\Entity\Dictionary\DayType Enum:string
109+
(
110+
[name] => publicHoliday
111+
[value] => Государственный праздник
112+
)
113+
[weekDay] => Shahruslan\ProductionCalendar\Entity\Dictionary\WeekDay Enum:string
114+
(
115+
[name] => sunday
116+
[value] => вс
117+
)
118+
[workingHours] => 0
119+
)
120+
[1] => Shahruslan\ProductionCalendar\Entity\Day Object
121+
(
122+
[date] => DateTimeImmutable Object
123+
(
124+
[date] => 2024-01-08 00:00:00.000000
125+
[timezone_type] => 3
126+
[timezone] => UTC
127+
)
128+
[type] => Shahruslan\ProductionCalendar\Entity\Dictionary\DayType Enum:string
129+
(
130+
[name] => publicHoliday
131+
[value] => Государственный праздник
132+
)
133+
[weekDay] => Shahruslan\ProductionCalendar\Entity\Dictionary\WeekDay Enum:string
134+
(
135+
[name] => monday
136+
[value] => пн
137+
)
138+
[workingHours] => 0
139+
)
140+
[2] => Shahruslan\ProductionCalendar\Entity\Day Object
141+
(
142+
[date] => DateTimeImmutable Object
143+
(
144+
[date] => 2024-01-09 00:00:00.000000
145+
[timezone_type] => 3
146+
[timezone] => UTC
147+
)
148+
[type] => Shahruslan\ProductionCalendar\Entity\Dictionary\DayType Enum:string
149+
(
150+
[name] => workingDay
151+
[value] => Рабочий день
152+
)
153+
[weekDay] => Shahruslan\ProductionCalendar\Entity\Dictionary\WeekDay Enum:string
154+
(
155+
[name] => tuesday
156+
[value] => вт
157+
)
158+
[workingHours] => 8
159+
)
160+
)
161+
[statistic] => Shahruslan\ProductionCalendar\Entity\Statistic Object
162+
(
163+
[calendarDays] => 3
164+
[calendarDaysWithoutHolidays] => 1
165+
[workDays] => 1
166+
[weekends] => 0
167+
[holidays] => 2
168+
[workingHours] => 8
169+
)
170+
)
171+
```
172+
173+
## Дополнительные настройки
174+
При необходимости можно получить производственный календарь для конкретного региона. Например, в Краснодарском крае
175+
14 мая 2024 года отмечается Радоница, и этот день объявлен выходным днем:
176+
```php
177+
$calendar = new Shahruslan\ProductionCalendar\Calendar('token');
178+
$data = $calendar->isWorkingDay(new DateTimeImmutable('14.05.2024'));
179+
var_dump($data);
180+
$data = $calendar->setRegion(23)->isWorkingDay(new DateTimeImmutable('14.05.2024'));
181+
var_dump($data);
182+
183+
```
184+
185+
Output:
186+
```shell
187+
bool(true)
188+
bool(false)
189+
```
190+
191+
192+
Помимо региона, еще можно настроить и другие параметры:
193+
194+
```php
195+
new Calendar(
196+
'token',
197+
isSixDayWeek: true, // включить учет по 6-ти дневной рабочей неделе
198+
isWeekendsOfSchrodinger: true, // учитывать ли так называемые нерабочие дни с сохранением заработной платы, которые начали практиковать с 2020 года (В период пандемии COVID-19)
199+
compact: true, // будут выводиться только особые дни, которые отличаются от обычного календаря
200+
);
201+
```

‎src/Calendar.php

+25-2
Original file line numberDiff line numberDiff line change
@@ -12,12 +12,12 @@
1212
use Psr\Http\Client\ClientInterface;
1313
use Psr\Http\Message\RequestFactoryInterface;
1414
use Shahruslan\ProductionCalendar\Entity\Dictionary\DayType;
15-
use Shahruslan\ProductionCalendar\Entity\Factory;
1615
use Shahruslan\ProductionCalendar\Entity\Period;
1716
use Shahruslan\ProductionCalendar\Exception\PeriodException;
17+
use Shahruslan\ProductionCalendar\Factory\Factory;
1818
use Shahruslan\ProductionCalendar\Validator\Validator;
1919

20-
class Calendar
20+
final class Calendar
2121
{
2222
private static string $host = 'https://production-calendar.ru';
2323
private readonly RequestFactoryInterface $requestFactory;
@@ -58,30 +58,53 @@ private function request(string $url): string
5858
return $response->getBody()->getContents();
5959
}
6060

61+
/**
62+
* Установить буквенный код страны для получения календаря.
63+
* В данный момент поддерживаются только ru и kz
64+
*/
6165
public function setCountry(string $country): Calendar
6266
{
6367
$this->country = $country;
6468
return $this;
6569
}
6670

71+
/**
72+
* Позволяет задать регион РФ (в ряде регионов присутствуют свои региональные праздники, для которых
73+
* производственный календарь отличается). В качестве номера региона задается однозначные или двузначные коды ГИБДД.
74+
* Трехзначные не поддерживаются.
75+
*/
6776
public function setRegion(?int $region): Calendar
6877
{
6978
$this->region = $region;
7079
return $this;
7180
}
7281

82+
/**
83+
* Настройка расчета по 6-ти дневной рабочей недели. По умолчанию расчет идет по 5-дневной недели.
84+
*/
7385
public function setIsSixDayWeek(bool $isSixDayWeek): Calendar
7486
{
7587
$this->isSixDayWeek = $isSixDayWeek;
7688
return $this;
7789
}
7890

91+
/**
92+
* Параметр показывает нужно ли учитывать так называемые нерабочие дни с сохранением заработной платы, которые
93+
* начали практиковать с 2020 года (В период пандемии COVID-19). В народе эти дни прозвали "выходные дни,
94+
* которые как бы есть, и одновременно которых как бы нет". Weekends of the Schrodinger. Так называемая отсылка к
95+
* всем известному коту Шредингера. По умолчанию параметр равен false, то есть подобные выходные не учитываются.
96+
*/
7997
public function setIsWeekendsOfSchrodinger(bool $isWeekendsOfSchrodinger): Calendar
8098
{
8199
$this->isWeekendsOfSchrodinger = $isWeekendsOfSchrodinger;
82100
return $this;
83101
}
84102

103+
/**
104+
* Если задать данному параметру значение true, то результат будет выдаваться в сокращенном формате, только особые
105+
* дни, которые отличаются от обычного календаря. По умолчанию этот параметр равен false и календарь выдает все
106+
* сутки заданного периода.
107+
*/
85108
public function setIsCompact(bool $isCompact): Calendar
86109
{
87110
$this->isCompact = $isCompact;

‎src/Entity/Factory.php ‎src/Factory/Factory.php

+4-2
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,20 @@
11
<?php
22

3-
namespace Shahruslan\ProductionCalendar\Entity;
3+
namespace Shahruslan\ProductionCalendar\Factory;
44

55
use DateTimeImmutable;
6+
use Shahruslan\ProductionCalendar\Entity\Day;
67
use Shahruslan\ProductionCalendar\Entity\Dictionary\Country;
78
use Shahruslan\ProductionCalendar\Entity\Dictionary\DayType;
89
use Shahruslan\ProductionCalendar\Entity\Dictionary\Region;
910
use Shahruslan\ProductionCalendar\Entity\Dictionary\WeekDay;
11+
use Shahruslan\ProductionCalendar\Entity\Period;
12+
use Shahruslan\ProductionCalendar\Entity\Statistic;
1013

1114
class Factory
1215
{
1316
public static function createPeriod(object $data): Period
1417
{
15-
echo '<pre>' . print_r($data, true) . '</pre>';
1618
$country = new Country($data->country_code, $data->country_text);
1719
$region = property_exists($data, 'region_id') ? new Region($data->region_id, $data->region_text) : null;
1820
$dateStart = new DateTimeImmutable($data->dt_start);

0 commit comments

Comments
 (0)