From c4f30de7a30d6d17398e95143916d254caea56ea Mon Sep 17 00:00:00 2001 From: Sarah Hoffmann Date: Sun, 15 Sep 2024 16:08:26 +0200 Subject: [PATCH] docs: remove all references to PHP --- docs/admin/Advanced-Installations.md | 2 +- docs/admin/Deployment-PHP.md | 151 ------------------------ docs/admin/Import.md | 37 ++---- docs/admin/Installation.md | 7 -- docs/api/Details.md | 15 +-- docs/api/Output.md | 2 +- docs/api/Overview.md | 9 -- docs/api/Reverse.md | 9 +- docs/api/Search.md | 2 - docs/customize/Settings.md | 39 +----- docs/develop/Development-Environment.md | 29 +---- docs/develop/Testing.md | 21 +--- docs/develop/Tokenizers.md | 81 +------------ docs/develop/overview.md | 4 +- mkdocs.yml | 3 +- settings/env.defaults | 10 -- 16 files changed, 28 insertions(+), 393 deletions(-) delete mode 100644 docs/admin/Deployment-PHP.md diff --git a/docs/admin/Advanced-Installations.md b/docs/admin/Advanced-Installations.md index f8232fb2..ac8da274 100644 --- a/docs/admin/Advanced-Installations.md +++ b/docs/admin/Advanced-Installations.md @@ -194,7 +194,7 @@ On the client side you now need to configure the import to point to the correct location of the library **on the database server**. Add the following line to your your `.env` file: -```php +``` NOMINATIM_DATABASE_MODULE_PATH="" ``` diff --git a/docs/admin/Deployment-PHP.md b/docs/admin/Deployment-PHP.md deleted file mode 100644 index 9416c53e..00000000 --- a/docs/admin/Deployment-PHP.md +++ /dev/null @@ -1,151 +0,0 @@ -# Deploying Nominatim using the PHP frontend - -!!! danger - The PHP frontend is deprecated and will be removed in Nominatim 5.0. - -The Nominatim API is implemented as a PHP application. The `website/` directory -in the project directory contains the configured website. You can serve this -in a production environment with any web server that is capable to run -PHP scripts. - -This section gives a quick overview on how to configure Apache and Nginx to -serve Nominatim. It is not meant as a full system administration guide on how -to run a web service. Please refer to the documentation of -[Apache](https://httpd.apache.org/docs/current/) and -[Nginx](https://nginx.org/en/docs/) -for background information on configuring the services. - -!!! Note - Throughout this page, we assume your Nominatim project directory is - located in `/srv/nominatim-project` and you have installed Nominatim - using the default installation prefix `/usr/local`. If you have put it - somewhere else, you need to adjust the commands and configuration - accordingly. - - We further assume that your web server runs as user `www-data`. Older - versions of CentOS may still use the user name `apache`. You also need - to adapt the instructions in this case. - -## Making the website directory accessible - -You need to make sure that the `website` directory is accessible for the -web server user. You can check that the permissions are correct by accessing -on of the php files as the web server user: - -``` sh -sudo -u www-data head -n 1 /srv/nominatim-project/website/search.php -``` - -If this shows a permission error, then you need to adapt the permissions of -each directory in the path so that it is executable for `www-data`. - -If you have SELinux enabled, further adjustments may be necessary to give the -web server access. At a minimum the following SELinux labelling should be done -for Nominatim: - -``` sh -sudo semanage fcontext -a -t httpd_sys_content_t "/usr/local/nominatim/lib/lib-php(/.*)?" -sudo semanage fcontext -a -t httpd_sys_content_t "/srv/nominatim-project/website(/.*)?" -sudo semanage fcontext -a -t lib_t "/srv/nominatim-project/module/nominatim.so" -sudo restorecon -R -v /usr/local/lib/nominatim -sudo restorecon -R -v /srv/nominatim-project -``` - -## Nominatim with Apache - -### Installing the required packages - -With Apache you can use the PHP module to run Nominatim. - -Under Ubuntu/Debian install them with: - -``` sh -sudo apt install apache2 libapache2-mod-php -``` - -### Configuring Apache - -Make sure your Apache configuration contains the required permissions for the -directory and create an alias: - -``` apache - - Options FollowSymLinks MultiViews - AddType text/html .php - DirectoryIndex search.php - Require all granted - -Alias /nominatim /srv/nominatim-project/website -``` - -After making changes in the apache config you need to restart apache. -The website should now be available on `http://localhost/nominatim`. - -## Nominatim with Nginx - -### Installing the required packages - -Nginx has no built-in PHP interpreter. You need to use php-fpm as a daemon for -serving PHP cgi. - -On Ubuntu/Debian install nginx and php-fpm with: - -``` sh -sudo apt install nginx php-fpm -``` - -### Configure php-fpm and Nginx - -By default php-fpm listens on a network socket. If you want it to listen to a -Unix socket instead, change the pool configuration -(`/etc/php//fpm/pool.d/www.conf`) as follows: - -``` ini -; Replace the tcp listener and add the unix socket -listen = /var/run/php-fpm-nominatim.sock - -; Ensure that the daemon runs as the correct user -listen.owner = www-data -listen.group = www-data -listen.mode = 0666 -``` - -Tell nginx that php files are special and to fastcgi_pass to the php-fpm -unix socket by adding the location definition to the default configuration. - -``` nginx -root /srv/nominatim-project/website; -index search.php; -location / { - try_files $uri $uri/ @php; -} - -location @php { - fastcgi_param SCRIPT_FILENAME "$document_root$uri.php"; - fastcgi_param PATH_TRANSLATED "$document_root$uri.php"; - fastcgi_param QUERY_STRING $args; - fastcgi_pass unix:/var/run/php-fpm-nominatim.sock; - fastcgi_index index.php; - include fastcgi_params; -} - -location ~ [^/]\.php(/|$) { - fastcgi_split_path_info ^(.+?\.php)(/.*)$; - if (!-f $document_root$fastcgi_script_name) { - return 404; - } - fastcgi_pass unix:/var/run/php-fpm-nominatim.sock; - fastcgi_index search.php; - include fastcgi.conf; -} -``` - -Restart the nginx and php-fpm services and the website should now be available -at `http://localhost/`. - -## Nominatim with other webservers - -Users have created instructions for other webservers: - -* [Caddy](https://github.com/osm-search/Nominatim/discussions/2580) - diff --git a/docs/admin/Import.md b/docs/admin/Import.md index 5a365b23..3f248b0e 100644 --- a/docs/admin/Import.md +++ b/docs/admin/Import.md @@ -257,8 +257,8 @@ successfully. nominatim admin --check-database ``` -Now you can try out your installation by executing a simple query on the -command line: +If you have installed the `nominatim-api` package, then you can try out +your installation by executing a simple query on the command line: ``` sh nominatim search --query Berlin @@ -270,10 +270,8 @@ or, when you have a reverse-only installation: nominatim reverse --lat 51 --lon 45 ``` -If you want to run Nominatim as a service, you need to make a choice between -running the modern Python frontend and the legacy PHP frontend. -Make sure you have installed the right packages as per -[Installation](Installation.md#software). +If you want to run Nominatim as a service, make sure you have installed +the right packages as per [Installation](Installation.md#software). #### Testing the Python frontend @@ -291,36 +289,15 @@ or, if you prefer to use Starlette instead of Falcon as webserver, nominatim serve --engine starlette ``` -Go to `http://localhost:8088/status.php` and you should see the message `OK`. -You can also run a search query, e.g. `http://localhost:8088/search.php?q=Berlin` +Go to `http://localhost:8088/status` and you should see the message `OK`. +You can also run a search query, e.g. `http://localhost:8088/search?q=Berlin` or, for reverse-only installations a reverse query, -e.g. `http://localhost:8088/reverse.php?lat=27.1750090510034&lon=78.04209025`. +e.g. `http://localhost:8088/reverse?lat=27.1750090510034&lon=78.04209025`. Do not use this test server in production. To run Nominatim via webservers like Apache or nginx, please continue reading [Deploy the Python frontend](Deployment-Python.md). -#### Testing the PHP frontend - -!!! danger - The PHP fronted is deprecated and will be removed in Nominatim 5.0. - -You can run a small test server with the PHP frontend like this: - -```sh -nominatim serve --engine php -``` - -Go to `http://localhost:8088/status.php` and you should see the message `OK`. -You can also run a search query, e.g. `http://localhost:8088/search.php?q=Berlin` -or, for reverse-only installations a reverse query, -e.g. `http://localhost:8088/reverse.php?lat=27.1750090510034&lon=78.04209025`. - -Do not use this test server in production. -To run Nominatim via webservers like Apache or nginx, please continue reading -[Deploy the PHP frontend](Deployment-PHP.md). - - ## Enabling search by category phrases diff --git a/docs/admin/Installation.md b/docs/admin/Installation.md index e67371bd..38c4d601 100644 --- a/docs/admin/Installation.md +++ b/docs/admin/Installation.md @@ -72,13 +72,6 @@ For running the Python frontend: * [starlette](https://www.starlette.io/) * [uvicorn](https://www.uvicorn.org/) -For running the legacy PHP frontend (deprecated, will be removed in Nominatim 5.0): - - * [PHP](https://php.net) (7.3+) - * PHP-pgsql - * PHP-intl (bundled with PHP) - - For dependencies for running tests and building documentation, see the [Development section](../develop/Development-Environment.md). diff --git a/docs/api/Details.md b/docs/api/Details.md index c50378c5..b836efd3 100644 --- a/docs/api/Details.md +++ b/docs/api/Details.md @@ -59,13 +59,6 @@ When set, then JSON output will be wrapped in a callback function with the given name. See [JSONP](https://en.wikipedia.org/wiki/JSONP) for more information. -| Parameter | Value | Default | -|-----------| ----- | ------- | -| pretty | 0 or 1 | 0 | - -`[PHP-only]` Add indentation to the output to make it more human-readable. - - ### Output details | Parameter | Value | Default | @@ -95,10 +88,8 @@ members. |-----------| ----- | ------- | | hierarchy | 0 or 1 | 0 | -Include details of places lower in the address hierarchy. - -`[Python-only]` will only return properly parented places. These are address -or POI-like places that reuse the address of their parent street or place. +Include details of POIs and address that depend on the place. Only POIs +that use this place to determine their address will be returned. | Parameter | Value | Default | |-----------| ----- | ------- | @@ -129,7 +120,7 @@ as the ["Accept-Language" HTTP header](https://developer.mozilla.org/en-US/docs/ ##### JSON -[https://nominatim.openstreetmap.org/details.php?osmtype=W&osmid=38210407&format=json](https://nominatim.openstreetmap.org/details.php?osmtype=W&osmid=38210407&format=json) +[https://nominatim.openstreetmap.org/details?osmtype=W&osmid=38210407&format=json](https://nominatim.openstreetmap.org/details?osmtype=W&osmid=38210407&format=json) ```json diff --git a/docs/api/Output.md b/docs/api/Output.md index 029f78bc..75220cf5 100644 --- a/docs/api/Output.md +++ b/docs/api/Output.md @@ -168,7 +168,7 @@ Additional information requested with `addressdetails=1`, `extratags=1` and + more_url="https://nominatim.openstreetmap.org/search?q=london&addressdetails=1&extratags=1&exclude_place_ids=100149&format=xml&accept-language=en-US%2Cen%3Bq%3D0.7%2Cde%3Bq%3D0.3"> "" Request time is the time when the request was started. The execution time is -given in seconds and corresponds to the time the query took executing in PHP. +given in seconds and includes the entire time the query was queued and executed +in the frontend. type contains the name of the endpoint used. Can be used as the same time as NOMINATIM_LOG_DB. diff --git a/docs/develop/Development-Environment.md b/docs/develop/Development-Environment.md index fd7820c6..441556ff 100644 --- a/docs/develop/Development-Environment.md +++ b/docs/develop/Development-Environment.md @@ -26,12 +26,9 @@ following packages should get you started: ## Prerequisites for testing and documentation The Nominatim test suite consists of behavioural tests (using behave) and -unit tests (using PHPUnit for PHP code and pytest for Python code). -It has the following additional requirements: +unit tests (using pytest). It has the following additional requirements: * [behave test framework](https://behave.readthedocs.io) >= 1.2.6 -* [phpunit](https://phpunit.de) (9.5 is known to work) -* [PHP CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) * [Pylint](https://pylint.org/) (CI always runs the latest version from pip) * [mypy](http://mypy-lang.org/) (plus typing information for external libs) * [Python Typing Extensions](https://github.com/python/typing_extensions) (for Python < 3.9) @@ -63,7 +60,7 @@ The easiest way, to handle these Python dependencies is to run your development from within a virtual environment. ```sh -sudo apt install libsqlite3-mod-spatialite php-cli +sudo apt install libsqlite3-mod-spatialite ``` To set up the virtual environment with all necessary packages run: @@ -86,28 +83,6 @@ Now enter the virtual environment whenever you want to develop: . ~/nominatim-dev-venv/bin/activate ``` -For installing the PHP development tools, run: - -```sh -sudo apt install php-cgi phpunit php-codesniffer -``` - -If your distribution does not have PHPUnit 7.3+, you can install it (as well -as CodeSniffer) via composer: - -``` -sudo apt-get install composer -composer global require "squizlabs/php_codesniffer=*" -composer global require "phpunit/phpunit=8.*" -``` - -The binaries are found in `.config/composer/vendor/bin`. You need to add this -to your PATH: - -``` -echo 'export PATH=~/.config/composer/vendor/bin:$PATH' > ~/.profile -``` - ### Running Nominatim during development The source code for Nominatim can be found in the `src` directory and can diff --git a/docs/develop/Testing.md b/docs/develop/Testing.md index c220f4e4..d57ab319 100644 --- a/docs/develop/Testing.md +++ b/docs/develop/Testing.md @@ -8,7 +8,7 @@ the tests, see the [Development setup chapter](Development-Environment.md). There are two kind of tests in this test suite. There are functional tests which test the API interface using a BDD test framework and there are unit -tests for specific PHP functions. +tests for the Python code. This test directory is structured as follows: @@ -20,28 +20,11 @@ This test directory is structured as follows: | +- db Tests for internal data processing on import and update | +- api Tests for API endpoints (search, reverse, etc.) | - +- php PHP unit tests +- python Python unit tests +- testdb Base data for generating API test database +- testdata Additional test data used by unit tests ``` -## PHP Unit Tests (`test/php`) - -Unit tests for PHP code can be found in the `php/` directory. They test selected -PHP functions. Very low coverage. - -To execute the test suite run - - cd test/php - UNIT_TEST_DSN='pgsql:dbname=nominatim_unit_tests' phpunit ../ - -It will read phpunit.xml which points to the library, test path, bootstrap -strip and sets other parameters. - -It will use (and destroy) a local database 'nominatim_unit_tests'. You can set -a different connection string with e.g. UNIT_TEST_DSN='pgsql:dbname=foo_unit_tests'. - ## Python Unit Tests (`test/python`) Unit tests for Python code can be found in the `python/` directory. The goal is @@ -118,7 +101,7 @@ and compromises the following data: * extract of Autauga country, Alabama, US (for tests against Tiger data) * additional data from `test/testdb/additional_api_test.data.osm` -API tests should only be testing the functionality of the website PHP code. +API tests should only be testing the functionality of the website frontend code. Most tests should be formulated as BDD DB creation tests (see below) instead. ### DB Creation Tests (`test/bdd/db`) diff --git a/docs/develop/Tokenizers.md b/docs/develop/Tokenizers.md index 03988ce0..f4a55adc 100644 --- a/docs/develop/Tokenizers.md +++ b/docs/develop/Tokenizers.md @@ -91,14 +91,9 @@ for a custom tokenizer implementation. ### Directory Structure -Nominatim expects two files for a tokenizer: - -* `nominatim/tokenizer/_tokenizer.py` containing the Python part of the - implementation -* `lib-php/tokenizer/_tokenizer.php` with the PHP part of the - implementation - -where `` is a unique name for the tokenizer consisting of only lower-case +Nominatim expects a single file `src/nominatim_db/tokenizer/_tokenizer.py` +containing the Python part of the implementation. +`` is a unique name for the tokenizer consisting of only lower-case letters, digits and underscore. A tokenizer also needs to install some SQL functions. By convention, these should be placed in `lib-sql/tokenizer`. @@ -282,73 +277,3 @@ permanently. The indexer calls this function when all processing is done and replaces the content of the `token_info` column with the returned value before the trigger stores the information in the database. May return NULL if no information should be stored permanently. - -### PHP Tokenizer class - -The PHP tokenizer class is instantiated once per request and responsible for -analyzing the incoming query. Multiple requests may be in flight in -parallel. - -The class is expected to be found under the -name of `\Nominatim\Tokenizer`. To find the class the PHP code includes the file -`tokenizer/tokenizer.php` in the project directory. This file must be created -when the tokenizer is first set up on import. The file should initialize any -configuration variables by setting PHP constants and then require the file -with the actual implementation of the tokenizer. - -The tokenizer class must implement the following functions: - -```php -public function __construct(object &$oDB) -``` - -The constructor of the class receives a database connection that can be used -to query persistent data in the database. - -```php -public function checkStatus() -``` - -Check that the tokenizer can access its persistent data structures. If there -is an issue, throw an `\Exception`. - -```php -public function normalizeString(string $sTerm) : string -``` - -Normalize string to a form to be used for comparisons when reordering results. -Nominatim reweighs results how well the final display string matches the actual -query. Before comparing result and query, names and query are normalised against -this function. The tokenizer can thus remove all properties that should not be -taken into account for reweighing, e.g. special characters or case. - -```php -public function tokensForSpecialTerm(string $sTerm) : array -``` - -Return the list of special term tokens that match the given term. - -```php -public function extractTokensFromPhrases(array &$aPhrases) : TokenList -``` - -Parse the given phrases, splitting them into word lists and retrieve the -matching tokens. - -The phrase array may take on two forms. In unstructured searches (using `q=` -parameter) the search query is split at the commas and the elements are -put into a sorted list. For structured searches the phrase array is an -associative array where the key designates the type of the term (street, city, -county etc.) The tokenizer may ignore the phrase type at this stage in parsing. -Matching phrase type and appropriate search token type will be done later -when the SearchDescription is built. - -For each phrase in the list of phrases, the function must analyse the phrase -string and then call `setWordSets()` to communicate the result of the analysis. -A word set is a list of strings, where each string refers to a search token. -A phrase may have multiple interpretations. Therefore a list of word sets is -usually attached to the phrase. The search tokens themselves are returned -by the function in an associative array, where the key corresponds to the -strings given in the word sets. The value is a list of search tokens. Thus -a single string in the list of word sets may refer to multiple search tokens. - diff --git a/docs/develop/overview.md b/docs/develop/overview.md index b5625a88..aedce990 100644 --- a/docs/develop/overview.md +++ b/docs/develop/overview.md @@ -20,5 +20,5 @@ and can be found in the files in the `sql/functions/` directory. The __search frontend__ implements the actual API. It takes search and reverse geocoding queries from the user, looks up the data and -returns the results in the requested format. This part is written in PHP -and can be found in the `lib/` and `website/` directories. +returns the results in the requested format. This part is located in the +`nominatim-api` package. The source code can be found in `src/nominatim_api`. diff --git a/mkdocs.yml b/mkdocs.yml index b6fd0ec7..6a24e816 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -26,8 +26,7 @@ nav: - 'Basic Installation': 'admin/Installation.md' - 'Import' : 'admin/Import.md' - 'Update' : 'admin/Update.md' - - 'Deploy (Python frontend)' : 'admin/Deployment-Python.md' - - 'Deploy (PHP frontend)' : 'admin/Deployment-PHP.md' + - 'Deploy' : 'admin/Deployment-Python.md' - 'Nominatim UI' : 'admin/Setup-Nominatim-UI.md' - 'Advanced Installations' : 'admin/Advanced-Installations.md' - 'Maintenance' : 'admin/Maintenance.md' diff --git a/settings/env.defaults b/settings/env.defaults index f4c33e77..8aee4a0f 100644 --- a/settings/env.defaults +++ b/settings/env.defaults @@ -177,16 +177,6 @@ NOMINATIM_MAPICON_URL= # When unset, the local language (i.e. the name tag without suffix) will be used. NOMINATIM_DEFAULT_LANGUAGE= -# Enable a special batch query mode. -# This feature is currently undocumented and potentially broken. -NOMINATIM_SEARCH_BATCH_MODE=no - -# Threshold for searches by name only. -# Threshold where the lookup strategy in the database is switched. If there -# are less occurrences of a tem than given, the search does the lookup only -# against the name, otherwise it uses indexes for name and address. -NOMINATIM_SEARCH_NAME_ONLY_THRESHOLD=500 - # Maximum number of OSM ids accepted by /lookup. NOMINATIM_LOOKUP_MAX_COUNT=50 -- 2.39.5