ergnuor/sphinx-config

A PHP Sphinx config helper

SphinxConfig

, _(*1)

About

This is the Sphinx configuration helper, which extends block inheritance and allows you to integrate configuration into your application through the possibility of using placeholders., _(*2)

Usage

Standalone

For that case you may use common console command: searchd -c /path/to/sphinx/config/preciousConfig.conf, _(*3)

And /path/to/sphinx/config/preciousConfig.conf file should contents something like this:, _(*4)

#!/usr/bin/php

<?php
// generated by composer --dump-autoload
require_once '/path/to/autoload/autoload.php';

use Ergnuor\SphinxConfig\Config;

$config = Config::phpArrayToNativeConfigStdout('/path/to/config/source');
$config ->transform('preciousConfig');
   ```

### Application integrated
You may integrate SphinxConfig into your application and create script that generates configuration file and runs desired Sphinx command.
So script may looks like this:
```php

//...

use Ergnuor\SphinxConfig\Config;

$config = Config::phpArrayToNativeConfigFile(
    '/path/to/config/source',
    '/path/to/sphinx/config'
);
$config->transform('preciousConfig');

exec('searchd -c /path/to/sphinnx/config/presiousConfig.conf');

//...

In any case you need to describe a source configuration., _(*5)

Prerequisites

SphinxConfig has no dependencies except for PHP 5.6+, _(*6)

Structure

Configuration structure

At this moment configuration is described by PHP arrays (more formats are planned). Here is a simple example of configuration structure:, _(*7)

<?php
return [
   'source' => [
       'main' => [
           'sql_query_pre' => [
               'SET NAMES utf8',
               'SET CHARACTER SET utf8'
           ],
           // ... all other setting
       ],
   ],

   'index' => [
       'main' => [
           'source' => 'main',
           'path' => '/path/to/main',
           // ... all other setting
       ],
   ],

   'indexer' => [
       'mem_limit' => '1024M',
       // ... all other setting
   ],

   'searchd' => [
       'listen' => 'localhost:9306:mysql41',
       // ... all other setting
   ],

   'common' => [
       'lemmatizer_base' => '/usr/local/share/sphinx/dicts/',
       // ... all other setting
   ],
];

Source and index sections consist of blocks. Blocks, as well as indexer, searchd and common sections, contain parameters., _(*8)

File structure convention

Here is a typical full file structure of configuration:, _(*9)

├── preciousConfig
│   ├── sectionType
│   │   └── blockName.php      # Block is located in a separate file
│   └── sectionType.php        # Section is located in a separate file
└── preciousConfig.php         # Whole configuration is located in one file

You don't have to describe a structure of configuration as comprehensively as shown above. You can choose one of the following options or combine them at your own discretion: - An entire configuration is located in one file.
For example: /path/to/configs/preciousConfig.php, - Section is located in a separate file.
For example: /path/to/configs/preciousConfig/sectionType.php, - Block is located in a separate file.
For example: /path/to/configs/preciousConfig/sectionType/blockName.php. This option may be useful for storing common parameters used by different configurations. For more information see inheritance between configurations section., _(*10)

Inheritance

To inherit blocks you should use 'extends' parameter with the name of parent block as a value.
For example:, _(*11)

<?php
return [
   'source' => [
       'main' => [
           // ... other block settings
       ],
       'delta' => [
           'extends' => 'main',
           // ... pther block settings
       ]
   ],
];

Inheritance of multi-value parameters

Values of a multi-value parameter are appended to values of a parent block parameter by default. To ignore values of the parent block, you must use :clear modifier.
For example:, _(*12)

'sql_query_pre:clear' => [
   'SET NAMES utf8',
   // ... other pre queries
],

You can also specify an alias for the value of the multi-value parameter. So, you can refer to the value in child blocks and override it.
For example:, _(*13)

<?php
return [
    'source' => [
        'main' => [
            'sql_query_pre' => [
                'SET NAMES utf8',
                // ... other pre queries
                'sph_counter' => 'INSERT INTO sphCounter  (indexingStartedAt, caption)
                    VALUES(NOW(), \'main\')
                    ON DUPLICATE KEY UPDATE indexingStartedAt = now()'
            ],
            // ... other block settings
        ],
        'delta' => [
            'extends' => 'main',
            'sql_query_pre' => [
                'sph_counter' => 'INSERT INTO sphCounter  (indexingStartedAt, caption)
                    VALUES(NOW(), \'delta\')
                    ON DUPLICATE KEY UPDATE indexingStartedAt = now()'
             ],
             // ... other block settings
        ]
    ],
];

And get the following configuration as a result:, _(*14)

source main {
    sql_query_pre = SET NAMES utf8
    // ... other pre queries
    sql_query_pre = INSERT INTO sphCounter  (indexingStartedAt, caption) \
        VALUES(NOW(), 'main') \
        ON DUPLICATE KEY UPDATE indexingStartedAt = now()
    // ... other block settings
}

source delta : main {
    sql_query_pre = SET NAMES utf8
    // ... other pre queries
    sql_query_pre = INSERT INTO sphCounter  (indexingStartedAt, caption) \
        VALUES(NOW(), 'delta') \
        ON DUPLICATE KEY UPDATE indexingStartedAt = now()
    // ... other block settings
}

With this approach you don’t need to copy all values of the multi-value parameter from the parent block. This example can be made even shorter by using placeholders., _(*15)

Inheritance between configurations

You can refer to the blocks from other configurations. For that you need to specify the configuration name and separate it from the block name with @ symbol. Note that configurations should be located in the same directory., _(*16)

The example of usage is storing database connection settings in /path/to/configs/common/source/connection.php block and referring to it from other configurations via 'extends' => 'common@connection' parameter., _(*17)

Note that in internal representation indexer, searchd and common sections are converted into sections containing self-titled blocks. This allows them to be used in the same way as source and index sections. So, as in the last example, you can store common settings for indexer, searchd and common sections in separate blocks and inherit from them., _(*18)

Placeholders

Each value of Sphinx parameter may contain a placeholder in ::path.to.value:: format. Placeholder uses dot notation, so it is possible to extract values from multidimensional arrays. The replacement values themselves can contain placeholders. So placeholders are dereferenced recursively., _(*19)

There are two ways of passing values: - You can pass global values for entire configuration using setPlaceholderValues() method.
This may be useful for passing values from your application, for example such as database connection parameters. - Values could be specified locally for each block using 'placeholderValues' parameter,
Using this feature we can simplify the example from inheritance of multi-value parameters section:, _(*20)

return [
   'source' => [
       'main' => [
           'sql_query_pre' => [
               'SET NAMES utf8',
               // ... other queries
               'INSERT INTO sphCounter  (indexingStartedAt, caption)
                   VALUES(NOW(), \'::sourceName::\')
                   ON DUPLICATE KEY UPDATE indexingStartedAt = now()'
           ],
           'placeholderValues' => [
               'sourceName' => 'main',
           ],
           // ... other block settings
       ],
       'delta' => [
           'extends' => 'main',
           'placeholderValues' => [
               'sourceName' => 'delta',
           ],
           // ... other block settings
       ]
   ],
];

And get the following configuration as a result:, _(*21)

source main {
    sql_query_pre = SET NAMES utf8
    // ... other pre queries
    sql_query_pre = INSERT INTO sphCounter  (indexingStartedAt, caption) \
        VALUES(NOW(), 'main') \
        ON DUPLICATE KEY UPDATE indexingStartedAt = now()
    // ... other block settings
}

source delta : main {
    sql_query_pre = SET NAMES utf8
    // ... other pre queries
    sql_query_pre = INSERT INTO sphCounter  (indexingStartedAt, caption) \
        VALUES(NOW(), 'delta') \
        ON DUPLICATE KEY UPDATE indexingStartedAt = now()
    // ... other block settings
}

Parameter values

Multiline values are automatically padded with a trailing slash. This is useful when formatting queries., _(*22)

Custom parameters

Parameter will be ignored if its name starts with an underscore. This allows you to add parameters for internal use, for example, if the configuration is being pre-processed and you want to be able to configure this process., _(*23)

Configuration parameters list

• 'extends'
  Specifies the name of the parent block. Can refer to a block from another configuration located in the same directory. For that you must specify the configuration name separated from the block name with @ symbol.
  'extends' => 'blockName'
'extends' => 'otherConfig@blockName'
• 'placeholderValues'
  Values for placeholders,
• 'isPseudo'
  Marks the block as a pseudo block. Pseudo blocks don`t get into the resulting configuration. This may be useful for inheritance purposes if you want to create a container-block just for storing parameters that are common to other blocks.

License

This project is licensed under the Apache 2.0 - see the LICENSE file for details, _(*24)