# Eventilla WordPress plugin

Eventilla is SaaS based event management software available from www.eventilla.com/en/. It can be used to publish event landing pages, sending event invites, gathering registrations and selling tickets. Event manager has easy to use tools and comprehensive reports, surveys and all the features needed to run succesfull events. We also offer free mobile app to scan tickets with QR-codes.

You can show Eventilla events on your WordPress site either as a single event or as a list of events. Shortcode and Block Editor is supported.

Event lists can be filtered with tags added in Eventilla.

Because events are saved as custom posts, it is possible to query the posts with a custom wp-query.

Published in [official WordPress plugin repository](https://wordpress.org/plugins/eventilla-events/)

## Plugin development
This guide presumes that you have local WordPress installation running.

For local MacOS development [Laravel Valet](https://laravel.com/docs/11.x/valet) or [Laravel Herd](https://herd.laravel.com) are recommended environments to run local WordPress installation. 

### Starting the development
#### 1. Clone the repository to your PROJECT_FOLDER 
```
cd PROJECT_FOLDER
git clone git@gitlab.com:eventilla/wordpress-plugin-v2.git
```
#### 2. Add the plugin to your WordPress installation
```
# Symlink the plugin so development can happen in PROJECT_FOLDER
ln -s wordpress-plugin-v2 WORDPRESS_INSTALLATION_PATH/wp-content/plugins/eventilla-events
# Activate plugin
cd WORDPRESS_INSTALLATION_PATH
wp plugin activate eventilla-events
``` 
#### 3. Node
```
cd PROJECT_FOLDER
npm install
# Run node (if you develop React functionality)
npm run start
```

### Development practices
- Use feature/fix branches and PR's to master in Gitlab
- Use existing WP React components if available: see https://wordpress.github.io/gutenberg
- See [@wp-scripts](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/) about collection of reusable scripts tailored for WordPress development.
- See [WordPress's plugin development best practices](https://developer.wordpress.org/plugins/plugin-basics/best-practices/)

### React development
- Main file `public/build/index.tsx`
- Loaded: Eventilla_WP_Admin::enqueue_scripts();
- Uses TypeScript for type safety
- Integrates with WordPress components (@wordpress/components)
- Supports WordPress i18n (@wordpress/i18n)
- Hot reloading during development
- Production builds output to public/build/

### Rest routes
 The `Eventilla_WP_REST_API` implements custom REST API endpoints for the Eventilla WordPress plugin. It provides functionality for managing events, filters, and tools through WordPress's REST API.

#### Current Endpoints
The plugin currently provides the following endpoints under the `eventilla/v1` namespace:

- `GET /eventilla/v1/filters` - Retrieves filter data for the Eventilla Tools page
- `POST /eventilla/v1/events` - Fetches events with various filtering options
- `POST /eventilla/v1/events/update` - Queues events for update from the Eventilla Tools page

#### Adding a New Route

To add a new route to the API, follow these steps:

1. Add your route configuration to the `$routes` array in the class:

```php
private static $routes = [
    // ... existing routes ...
    'your-new-endpoint' => [
        'methods' => 'GET', // or 'POST', 'PUT', 'DELETE'
        'callback' => [self::class, 'your_callback_method'],
        'permission_callback' => [self::class, 'current_user_can_manage_options'],
    ],
];
```

2. Create the callback method in the class:

```php
public static function your_callback_method($request) {
    // Your endpoint logic here
    return rest_ensure_response($your_data);
}
```

3. The route will be automatically registered when the plugin initializes.

### Custom endpoints

The `Eventilla_WP_Router` class provides a simple routing system for WordPress that allows you to create custom endpoints accessible via `wp-load.php`.

The router listens for requests to `wp-load.php` with a specific namespace parameter (`eventilla_route`). When a matching request is found, it validates the request parameters and authentication (if required) before executing the corresponding callback function.

#### Adding a New Route

To add a new route, you need to add an entry to the `$routes` array in the `Eventilla_WP_Router` class. Here's the structure:

```php
'route_name' => [
    'parameters' => [
        'parameter_name' => true, // true means parameter is required
        // or
        'parameter_name' => ['value1', 'value2'], // array of allowed values
    ],
    'auth' => true, // whether authentication is required
    'auth_option' => 'option_name', // WordPress option name containing the secret
    'callback' => ['Class_Name', 'method_name'], // callback to execute
],
```

### Logs
You can define log level in settings to see debug information.

### Update changes
If there are any changes you need to run **just once** after the plugin is updated, add a new function to the `includes/class-eventilla-wp-updater.php` files `$updates` array. Key is the version number and value is the function name to be ran once from the class.

## Making new release
1. Merge feature branches via pull request (squash commits and delete branch after merge) to `master`
2. Pull `master` to local environment and test basic functionality
- Event updating works
- Admin views work
- New functionality works
3. Add new version info
Note that we are using [semver](https://semver.org/).
When publishing an update, update the version number 
- in `eventilla-wp.php` Plugin info 
- in the `eventilla-wp.php` file:`define('EVENTILLA_WP_VERSION', '1.9.0');`
4. Update release info to `README.txt`
At least add new version line below description.
5. Build npm for production `npm run build`
6. Commit and add tag 
Commit changes with new version number
```
git add eventilla-wp.php README.txt 
git commit -m"VERSION MUMBER HERE"
git tag -a [VERSION NUMBER] -m[SHORT DESCRIPTION ABOUT THE NEW VERSION]"
```

Finally, push the changes with the tag. OBS! This runs CI/CD pipeline in Gitlab which releases the changes to WordPress plugin repository.

```
git push origin master --tags
```



## Librariers

### Action Scheduler

Eventilla plugin uses [Action Scheduler library](https://actionscheduler.org/) to schedule actions. The repository has been added as a remote subtree `subtree-action-scheduler` to the plugin repository.

#### Updating Action Scheduler

Note that Action Scheduler utilizes [L-2 policy](https://developer.woocommerce.com/2023/10/24/action-scheduler-to-adopt-l-2-dependency-version-policy/) meaning, it supports the latest 2 versions of WordPress.

To update the library, run the following command:

```
git fetch subtree-action-scheduler <version tag>
git subtree pull --prefix libraries/action-scheduler subtree-action-scheduler <version tag> --squash
```