<commit_before># Katana [![Build Status](https://travis-ci.org/mitogh/Katana.svg?branch=master)](https://travis-ci.org/mitogh/Katana)

> Save disk space and creates custom images sizes only where is
required.

Custom filters to make sure the image sizes are generated only on pages or posts that requires the sizes on [WordPress](https://wordpress.org/), this will help to save some disk space of images that are not used at all on your WordPress installation.

![](/media/samurai.jpg)  
Picture from [WikiImages](https://pixabay.com/samurai-guerrero-caza-de-samurai-67662/)

## Previous version.

If you are using a version below 2, please make sure you take a look at
[the previous docs](readme-1.md) and if you are going to upgrade make
sure you follow the installation guide.

## Installation 

**This is not a plugin**, rather is a library that can be used with your
own plugin or your theme. 

1. You need to download the library using [composer](https://getcomposer.org/). In order to do this you can run the following command: 

```bash
composer require mitogh/katana
```

This will add the latest version of the library on your installation and
will create a vendor directory where the files are going to be located.

2. If you are using a plugin or `functions.php` from a theme you only
   need to include the following file: 

```php
include dirname( __FILE__ ) . '/vendor/autoload.php';
```

That will allow you to use any filter from the class from `Katana` or
any other package installed via composer.  

That's practically all the process you need to follow in order to
install the library, since the library automatically creates the object
that is used for create the post and page filters.

## Usage

This library comes with some filters that allows you edit what sizes of
images are generated under certain post types, page templates, post ID
or any other custom conditional.

## Default size

As a note or reminder take into account that the default image size is
always generated even if you remove all default sizes.

## Filters 

Each filter allow to return what sizes of images are needed for that
particular filter, the returned sizes represents the allowed images
sizes, each size is the name that was registered when you created an
image size using `add_image_size`.

### katana_refine_{post_type}  

`{post_type}`, can be any post type declared on the site, post page or
even a custom one, like movies.

This filter allows to refine the sizes of images for a certain post
type.

**Example**

This example remove all the sizes from all of the pages, so any time you
add an image on a page it wont create any new size of image. 

```php
add_filter('katana_refine_page', 'remove_all_sizes_from_pages');

function remove_all_sizes_from_pages( $sizes ){<commit_msg>Add custom filter example<commit_after># Katana [![Build Status](https://travis-ci.org/mitogh/Katana.svg?branch=master)](https://travis-ci.org/mitogh/Katana)

> Save disk space and creates custom images sizes only where is
required.

Custom filters to make sure the image sizes are generated only on pages or posts that requires the sizes on [WordPress](https://wordpress.org/), this will help to save some disk space of images that are not used at all on your WordPress installation.

![](/media/samurai.jpg)  
Picture from [WikiImages](https://pixabay.com/samurai-guerrero-caza-de-samurai-67662/)

## Previous version.

If you are using a version below 2, please make sure you take a look at
[the previous docs](readme-1.md) and if you are going to upgrade make
sure you follow the installation guide.

## Installation 

**This is not a plugin**, rather is a library that can be used with your
own plugin or your theme. 

1. You need to download the library using [composer](https://getcomposer.org/). In order to do this you can run the following command: 

```bash
composer require mitogh/katana
```

This will add the latest version of the library on your installation and
will create a vendor directory where the files are going to be located.

2. If you are using a plugin or `functions.php` from a theme you only
   need to include the following file: 

```php
include dirname( __FILE__ ) . '/vendor/autoload.php';
```

That will allow you to use any filter from the class from `Katana` or
any other package installed via composer.  

That's practically all the process you need to follow in order to
install the library, since the library automatically creates the object
that is used for create the post and page filters.

## Usage

This library comes with some filters that allows you edit what sizes of
images are generated under certain post types, page templates, post ID
or any other custom conditional.

## Default size

As a note or reminder take into account that the default image size is
always generated even if you remove all image sizes with the filters.

## Filters 

Each filter allow to return what sizes of images are needed for that
particular filter, the returned sizes represents the allowed images
sizes, each size is the name that was registered when you created an
image size using `add_image_size`.

By default Katana applies 3 filters in the following order: 

1. Filter by post_id - priority 10
2. Filter by post type - priority 20
3. Filter by template page - priority 30

About filter priorities: 

> Used to specify the order in which the functions associated with a particular action are executed. Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the filter.

So if you are creating your own filter make sure to take priorities into account.

### kata_refine

This is the filter triggered by Katana and is the one that you can use
to create custom conditionals or to create new filter names.

The filter sends two parameters, so you need to explicity specify the
number of arguments that are send to the filter: 

- `$sizes` An array with the sizes of the images availables on the site.
- `$id` The id of the post that triggers the filter.

For example you want to remove all the image sizes from a page that has
the title `tomacco`

```php
add_filer( 'katana_refine', function($sizes, $id) {
    $title = strtolower( get_the_title( $id ) );
    if ( $title === 'tomacco' ) {
      return [];
    } else {
      return $sizes;
    }
}, 10, 2);
```

### katana_refine_{post_type}  

`{post_type}`, can be any post type declared on the site, post page or
even a custom one, like movies.

This filter allows to refine the sizes of images for a certain post
type.

**Example**

This example remove all the sizes from all of the pages, so any time you
add an image on a page it wont create any new size of image. 

```php
add_filter('katana_refine_page', 'remove_all_sizes_from_pages');

function remove_all_sizes_from_pages( $sizes ){
{'fraction_non_alphanumeric': 0.06409694845962914, 'fraction_numerical': 0.004526208205577456, 'mean_word_length': 4.185465556396669, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 6, 'https://': 10, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '697922', 'n_tokens_mistral': 1901, 'n_tokens_neox': 1814, 'n_words': 1019}