# Northmill Online Shared
Contains code shared between several Northmill Online projects. Made available as a Composer package.


## Prerequisites
- PHP 8.2 or later
- Composer
- SSH key added to your GitLab account (including WSL, if applicable)

### Adding the package to your project

```bash
{
    "repositories": [
        {
            "type": "vcs",
            "url": "git@gitlab.com:moreflo-web/northmill-online-shared.git"
        }
    ],
    "require": {
        "northmill/online-shared": "^1.0.0"
    }
}
```

## Usage
### Setup
Create an instance of the shared class, and store it made available to your package.
This should be done ASAP, preferably directly in the main file of the plugin or theme.

#### Plugin

```php

$shared = new \Northmill_Online_Shared\Abstract_Plugin_Shared(
    plugin_file_path:        __FILE__, // Absolute path to the main file of the package loading the shared instance.
    template_loader_dir:     'views',  // OPTIONAL: Directory where template files are stored, relative to package_path.
    package_assets_dir:      'assets', // OPTIONAL: Directory where assets are stored, relative to package_path.
    is_woocommerce_required: true,     // OPTIONAL: Whether WooCommerce is required for the package to work.
    translations:            array(    // OPTIONAL: Translations for the package. Path is to the directory containing .po and .mo files, relative to package_path.
        array(
            'textdomain' => 'flo-sync',
            'path'       => 'languages',
        ),
    ),
    receipt_sync_class:      Receipt_Sync_Module::class // OPTIONAL: A class extending the Northmill_Online_Shared\Modules\Sync\Abstract_Receipt_Sync_Module class, used for syncing receipts.
);
```

#### Theme
```php
$shared = new Theme_Shared(
    plugin_file_path:        NORTHMILL_EXPRESS_PATH . 'style.css', // Absolute path to the main file of the package loading the shared instance.
    template_loader_dir:     'templates',                          // OPTIONAL: Directory where template files are stored, relative to package_path.
    package_assets_dir:      'assets',                             // OPTIONAL: Directory where assets are stored, relative to package_path.
    is_woocommerce_required: true,                                 // OPTIONAL: Whether WooCommerce is required for the package to work.
    translations:            array(                                // OPTIONAL: Translations for the package. Path is to the directory containing .po and .mo files, relative to package_path.
        array(
            'textdomain' => 'northmill-express-order',
            'path'       => 'languages',
        ),
    ),
);
```

#### Next

Then, on `plugins_loaded` or `after_setup_theme`, call the `setup` method on the shared instance.
```php
$shared->setup(
	settings_fields: array( // OPTIONAL: Settings fields to be added to the settings page, that will be created.
		array(
			'id'          => 'northmill_express_order_section_general',
			'target'      => 'setting',
			'target_name' => 'northmill-express-order-settings',
			'type'        => 'section', // See Northmill_Online_Shared\Modules\Admin\Pages\Page\Admin_Settings::html_field() for available types.
			'name'        => 'section_general', // This is how the field will be referred to in the settings.
			'label'       => __( 'General', 'northmill-express-order' ),
		)
	),
	additional_pages: array( // OPTIONAL: Data for additional admin pages to be created.
		array(
			'is_main_page' => true, // Whether the page should be added to the main menu.
			'class'        => Custom_Page::class, // Class to be used for the page, extending the Northmill_Online_Shared\Modules\Admin\Pages\Page\Abstract_Admin_Page class.
			'page_id'      => 'sync', // Unique ID of the page.
			'page_title'   => __( 'WP Northmill Sync', 'flo-sync' ), // Title of the page.
			'menu_title'   => __( 'Northmill Sync', 'flo-sync' ), // Title of the menu item.
			'extra'        => array( // Additional data for the page.
				'custom_callback' => array( Views_Admin::class, 'render_sync_page' ), // A custom callback function for rendering the admin page.
			),
		),
		array(
			'class'      => Custom_Page::class,
			'page_id'    => 'settings',
			'page_title' => 'WP Northmill Sync',
			'menu_title' => __( 'Settings', 'flo-sync' ),
			'extra'      => array(
				'custom_callback' => array( Views_Admin::class, 'render_settings_page' ),
			),
		),
	)
);
```

### Hooks
Here is a list of some of the hooks that are available in the shared instance.
Almost of the hooks end with the property `$shared->service_name_underscored`, which is derived from the package name.
This is to avoid conflicts with other packages using the shared instance.
Will be written as `$snu` below.

#### northmill_online_shared_admin_status_main_settings_$snu
Should load an array of all settings to be displayed at the admin status page.

#### northmill_online_shared_get_setting_\$setting_name_$snu
`$setting_name` is the name of the setting to get. This filters the value of the setting.

#### northmill_online_shared_admin_status_sections_$snu
Filters the array of sections to be displayed at the admin status page. You can add a section like this:
```php
$sections['bookkeeping'] = array(
	'title'   => __( 'Bookkeeping', 'flo-sync' ),
	'content' => $shared->template_loader->get_admin_template_part(
		'status/tab-bookkeeping',
		array(),
		false,
		true
	),
	'toc'     => array(
		array(
			'id'    => 'income-account-codes',
			'title' => __( 'Income Account Codes', 'flo-sync' ),
		),
		array(
			'id'    => 'article-account-codes',
			'title' => __( 'Article Account Codes', 'flo-sync' ),
			'sub'   => array(
				array(
					'id'    => 'table-wc_tax_rate_classes',
					'title' => 'Table wc_tax_rate_classes',
				),
			),
		),
	),
);
```

List of additional actions, not necessarily exhaustive:
- `northmill_online_shared_sync_receipt_setup_$snu`
- `northmill_online_shared_settings_page_updated`
- `northmill_online_shared_settings_page_updated_$snu`

List of additional filters, not necessarily exhaustive:
- `northmill_online_shared_get_request_response_silent_404_$snu`
- `northmill_online_shared_api_request_valid_body_keys_$snu`
- `northmill_online_shared_receipt_payment_gateway_map_$snu`
- `northmill_online_shared_settings_page_updated_$snu`
- `northmill_online_shared_constant_default_value`
- `northmill_online_shared_constant_default_value_$constant_name`
- `northmill_online_shared_admin_settings_field_$settings_id_$snu`
- `northmill_online_shared_get_setting_$snu`

### Constants
The shared instance contains a number of constants that can be set in wp-config.php to change the behavior of the shared instance.
- `NM_HOSTING` – Should be set to true for Northmill hosting.
- `NM_DEBUG` – Set to true to enable debug mode.
- `NM_LOG_DIR` – Directory where logs should be stored. Defaults to `/var/log/apache2/wp_monolog/`

### Helpers
There are a number of helper functions available in the shared instance.
Look in the `includes/Helpers` directory for more information.

### Abstracts
There are also a number of abstract classes available
made to speed up development in the packages using the shared instance.
Some of these are:
- Admin pages
- Hub API base
- Receipt Factory
- WP REST Routes

### Modules
There are a bunch of modules available in the shared instance:
- Admin - Handles admin pages and settings.
- Assets - Handles public assets.
- Debug - Handles debugging.
- i18n - Handles internationalization.
- Logger - Handles logging.
- Sync - Handles syncing of data.
- Template Loader – Handles loading of templates.

#### Logging
When setting up logging on a Northmill hosted site, the log will be stored in a file.
You should enable log rotation for that file.
