generated from spatie/package-skeleton-laravel
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #4 from AuroraWebSoftware/v2-dev
bismillah
- Loading branch information
Showing
1 changed file
with
241 additions
and
41 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,84 +1,284 @@ | ||
# This is my package acalendar | ||
# **Laravel ACalendar Package** | ||
|
||
[![Latest Version on Packagist](https://img.shields.io/packagist/v/aurorawebsoftware/acalendar.svg?style=flat-square)](https://packagist.org/packages/aurorawebsoftware/acalendar) | ||
[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/aurorawebsoftware/acalendar/run-tests.yml?branch=main&label=tests&style=flat-square)](https://github.com/aurorawebsoftware/acalendar/actions?query=workflow%3Arun-tests+branch%3Amain) | ||
[![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/aurorawebsoftware/acalendar/fix-php-code-style-issues.yml?branch=main&label=code%20style&style=flat-square)](https://github.com/aurorawebsoftware/acalendar/actions?query=workflow%3A"Fix+PHP+code+style+issues"+branch%3Amain) | ||
[![Total Downloads](https://img.shields.io/packagist/dt/aurorawebsoftware/acalendar.svg?style=flat-square)](https://packagist.org/packages/aurorawebsoftware/acalendar) | ||
The Laravel ACalendar package is designed to enrich Laravel applications with advanced event management capabilities. It allows developers to seamlessly integrate event functionalities into Eloquent models, manage event occurrences, and handle repeating events with ease. This guide outlines the package's main features, installation process, and usage with detailed examples. | ||
|
||
This is where your description should go. Limit it to a paragraph or two. Consider adding a small example. | ||
## **Features and Main Concepts** | ||
|
||
## Support us | ||
- **Flexible Event Management**: Create, update, and delete events directly associated with Eloquent models. | ||
- **Support for Various Event Types**: Handles different types of events, including single, all-day, ranged dates, and timed events. | ||
- **Repeating Events**: Comprehensive support for repeating events with customizable frequencies. | ||
- **Eloquent Model Integration**: Easy integration with any Eloquent model using a trait and interface. | ||
- **Dynamic Event Instances Generation**: Automatically handles the generation of event instances for repeating events within specified date ranges. | ||
- **Custom Event Collection Method**: Provides a **`byDay()`** method for grouping event instances, facilitating calendar views or daily summaries. | ||
|
||
[<img src="https://github-ads.s3.eu-central-1.amazonaws.com/ACalendar.jpg?t=1" width="419px" />](https://spatie.be/github-ad-click/ACalendar) | ||
## **Installation** | ||
|
||
We invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us). | ||
1. Install the package via Composer: | ||
|
||
We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards). | ||
```bash | ||
composer require aurorawebsoftware/acalendar | ||
|
||
## Installation | ||
``` | ||
|
||
You can install the package via composer: | ||
1. Publish the configuration and migration files: | ||
|
||
```bash | ||
composer require aurorawebsoftware/acalendar | ||
php artisan vendor:publish --provider="AuroraWebSoftware\ACalendar\ACalendarServiceProvider" | ||
|
||
``` | ||
|
||
You can publish and run the migrations with: | ||
1. Execute the migrations: | ||
|
||
```bash | ||
php artisan vendor:publish --tag="acalendar-migrations" | ||
php artisan migrate | ||
|
||
``` | ||
|
||
You can publish the config file with: | ||
## **Enums** | ||
|
||
### **Type Enum** | ||
|
||
- **`DATE_ALL_DAY`**: Events occurring throughout the day. | ||
- **`DATE_POINT`**: Events assigned to a specific date. | ||
- **`DATETIME_POINT`**: Events assigned to a specific datetime. | ||
- **`DATE_RANGE`**: Events spanning across multiple dates. | ||
- **`DATETIME_RANGE`**: Events with a specific start and end datetime. | ||
|
||
### **RepeatFrequency Enum** | ||
|
||
- **`DAY`**: Event repeats daily. | ||
- **`WEEK`**: Event repeats weekly. | ||
- **`MONTH`**: Event repeats monthly. | ||
- **`YEAR`**: Event repeats yearly. | ||
|
||
## **Integration with Models** | ||
|
||
Implement the **`EventableModelContract`** and use the **`HasEvents`** trait within your model: | ||
|
||
```php | ||
namespace App\Models; | ||
|
||
use AuroraWebSoftware\ACalendar\Contracts\EventableModelContract; | ||
use AuroraWebSoftware\ACalendar\Traits\HasEvents; | ||
use Illuminate\Database\Eloquent\Model; | ||
|
||
class Task extends Model implements EventableModelContract | ||
{ | ||
use HasEvents; | ||
|
||
protected $fillable = ['name']; | ||
|
||
public static function getModelType(): string | ||
{ | ||
return self::class; | ||
} | ||
|
||
public function getModelId(): int | ||
{ | ||
return $this->id; | ||
} | ||
|
||
public function getEventTitle(): ?string | ||
{ | ||
return $this->name; | ||
} | ||
} | ||
|
||
``` | ||
|
||
|
||
|
||
## **Usage Examples** | ||
|
||
### **Creating Events** | ||
|
||
```php | ||
$task = Task::find(1); | ||
$task->updateOrCreateEvent( | ||
key: 'deadline', | ||
type: Type::DATE_POINT, | ||
start: Carbon::tomorrow(), | ||
title: 'Preparing SRS Docs' | ||
); | ||
|
||
$task->updateOrCreateEvent( | ||
key: 'deadline', | ||
type: Type::DATE_POINT, | ||
start: Carbon::tomorrow(), | ||
title: 'Preparing SRS Docs' | ||
); | ||
|
||
```bash | ||
php artisan vendor:publish --tag="acalendar-config" | ||
``` | ||
|
||
This is the contents of the published config file: | ||
> Only one event can be created for a model with a key | ||
### **Retrieving Event Instances** | ||
|
||
- Dynamic method on an instance: | ||
|
||
```php | ||
return [ | ||
]; | ||
$events = $task->eventInstances('deadline', Carbon::now(), Carbon::now()->addMonth(1)); | ||
``` | ||
|
||
Optionally, you can publish the views using | ||
- Static method on the model class: | ||
|
||
```bash | ||
php artisan vendor:publish --tag="acalendar-views" | ||
```php | ||
$events = Task::allEventInstances('deadline', Carbon::now(), Carbon::now()->addMonth(1)); | ||
``` | ||
|
||
## Usage | ||
### **Handling Repeating Events** | ||
|
||
```php | ||
$aCalendar = new AuroraWebSoftware\ACalendar(); | ||
echo $aCalendar->echoPhrase('Hello, AuroraWebSoftware!'); | ||
$meeting = Meeting::find(1); | ||
$meeting->updateOrCreateEvent( | ||
key: 'Weekly Review', | ||
type: Type::DATETIME_POINT, | ||
start: Carbon::parse('next monday 10:00'), | ||
repeatFrequency: RepeatFrequency::WEEK, | ||
repeatPeriod: 1, | ||
title: 'Weekly Review Meeting' | ||
); | ||
|
||
``` | ||
|
||
## Testing | ||
### **Using `byDay` Method** | ||
|
||
The byDay() method in the Laravel ACalendar package groups event instances by their occurrence date, returning a collection where each key is a date and the value is a collection of events happening on that date. This method simplifies creating calendar views or daily schedules by organizing events in a date-indexed format, making it straightforward to display what events are happening on each day. | ||
|
||
- Facilitates the development of calendar interfaces by categorizing events by day. | ||
|
||
```php | ||
$eventInstances = $meeting->eventInstances(null, Carbon::now(), Carbon::now()->addWeeks(4)); | ||
$byDay = $eventInstances->byDay(); | ||
|
||
foreach ($byDay as $date => $events) { | ||
echo "Date: $date\n"; | ||
foreach ($events as $event) { | ||
echo "- {$event->title} at {$event->start->format('H:i')}\n"; | ||
} | ||
} | ||
|
||
``` | ||
|
||
|
||
|
||
|
||
|
||
|
||
## **Scenario Setup** | ||
|
||
Assuming we have three models - **`Conference`**, **`Webinar`**, and **`Exhibition`**, each integrated with the ACalendar package as shown in previous examples. These models will demonstrate different event types, such as **`DATE_ALL_DAY`**, **`DATE_RANGE`**, and **`DATETIME_RANGE`**. | ||
|
||
### **Conference: All-Day Event** | ||
|
||
Conferences often last the entire day. Here's how you might set up an all-day event for a conference: | ||
|
||
```php | ||
$conference = Conference::create(['name' => 'Tech Innovators Conference', 'description' => 'A gathering of technology innovators.']); | ||
|
||
$conference->updateOrCreateEvent( | ||
key: 'tech_innovators_2024', | ||
type: Type::DATE_ALL_DAY, | ||
start: Carbon::parse('2024-09-10'), | ||
title: 'Tech Innovators Conference - All Day' | ||
); | ||
|
||
``` | ||
|
||
### **Webinar: Date Range Event** | ||
|
||
Webinars can span multiple days. This example demonstrates creating an event that covers a range of dates: | ||
|
||
```php | ||
$webinar = Webinar::create(['title' => 'Digital Marketing 101', 'host' => 'Marketing Gurus']); | ||
|
||
$webinar->updateOrCreateEvent( | ||
key: 'digital_marketing_101', | ||
type: Type::DATE_RANGE, | ||
start: Carbon::parse('2024-10-05'), | ||
end: Carbon::parse('2024-10-07'), | ||
title: 'Digital Marketing 101 Webinar' | ||
); | ||
|
||
``` | ||
|
||
### **Exhibition: DateTime Range Event** | ||
|
||
Exhibitions may have specific start and end times. Here's how you'd set up an event with a datetime range: | ||
|
||
```php | ||
$exhibition = Exhibition::create(['name' => 'Artists of the 21st Century', 'location' => 'City Art Gallery']); | ||
|
||
$exhibition->updateOrCreateEvent( | ||
key: '21st_century_artists', | ||
type: Type::DATETIME_RANGE, | ||
start: Carbon::parse('2024-11-20 09:00'), | ||
end: Carbon::parse('2024-11-20 17:00'), | ||
title: 'Artists of the 21st Century Exhibition' | ||
); | ||
|
||
``` | ||
|
||
## **Querying and Displaying Event Instances** | ||
|
||
### **Displaying Upcoming Conferences** | ||
|
||
Retrieve and display all upcoming conferences for the next year: | ||
|
||
```php | ||
phpCopy code | ||
$upcomingConferences = Conference::allEventInstances( | ||
null, | ||
Carbon::now(), | ||
Carbon::now()->addYear(1) | ||
); | ||
|
||
foreach ($upcomingConferences as $event) { | ||
echo "Conference: {$event->title} on {$event->start->toDateString()}\n"; | ||
} | ||
|
||
```bash | ||
composer test | ||
``` | ||
|
||
## Changelog | ||
### **Webinar Schedule for the Next Month** | ||
|
||
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. | ||
Generate a schedule of all webinars happening in the next month, grouped by day: | ||
|
||
## Contributing | ||
```php | ||
phpCopy code | ||
$nextMonthWebinars = Webinar::allEventInstances( | ||
null, | ||
Carbon::now()->addMonth(), | ||
Carbon::now()->addMonths(2) | ||
)->byDay(); | ||
|
||
foreach ($nextMonthWebinars as $date => $webinars) { | ||
echo "Date: $date\n"; | ||
foreach ($webinars as $webinar) { | ||
echo "- Webinar: {$webinar->title} from {$webinar->start->toDateString()} to {$webinar->end->toDateString()}\n"; | ||
} | ||
} | ||
|
||
``` | ||
|
||
### **Exhibition Hours** | ||
|
||
For exhibitions, it might be useful to know the exact opening and closing times: | ||
|
||
```php | ||
phpCopy code | ||
$exhibitionDetails = Exhibition::allEventInstances('21st_century_artists', Carbon::now(), Carbon::now()->addMonth(1)); | ||
|
||
foreach ($exhibitionDetails as $detail) { | ||
echo "Exhibition: {$detail->title}, Start: {$detail->start->toDateTimeString()}, End: {$detail->end->toDateTimeString()}\n"; | ||
} | ||
|
||
``` | ||
|
||
Please see [CONTRIBUTING](CONTRIBUTING.md) for details. | ||
These examples illustrate just a few of the many possibilities enabled by the Laravel ACalendar package for managing events. By leveraging different event types and repeat frequencies, developers can tailor the package to meet a wide array of event management needs within their Laravel applications. | ||
|
||
## Security Vulnerabilities | ||
|
||
Please review [our security policy](../../security/policy) on how to report security vulnerabilities. | ||
|
||
## Credits | ||
|
||
- [Aurora Web Software Team](https://github.com/AuroraWebSoftware) | ||
- [All Contributors](../../contributors) | ||
|
||
## License | ||
|
||
The MIT License (MIT). Please see [License File](LICENSE.md) for more information. | ||
This Laravel ACalendar package guide aims to provide a solid foundation for integrating and utilizing event management within your Laravel applications. By following the installation instructions and exploring the comprehensive examples, you can leverage the package's functionalities to enhance your projects with sophisticated event handling capabilities. |