README in Deutsch

kirchen-im-web.de - Directory of Churchy Websites and Social Network Pages

We want to show that many parishes, regional churches and dioceses do a good job in public relations and present those with their websites and social network pages at a map and tabularly. kirchen-im-web.de also compares the follower numbers of the social media pages.

Our Project is oecumenic, i. e. regardless whether Protestants, Catholic or free church - all can participate. You can simply add your church using our form.

Features

• map with all churches which can be filtered according to denomination and network
• table and social media comparison with filtering according to name, postal code, city, country, denomination, type, network
• details page for every church showing all websites and networks, map and church hierarchy and offering download of the social media follower history
• form to add new churches
• statistics and downloadable open data
• available in English and German

Link check and follower update

The script cron.php

• checks whether the listed websites are still online
• and updates the follower count of the listed social media accounts. Non-public pages can be excluded via followerStatus = 2.

followerStatus = 0 means that the last follower update failed.

API Documentation

kirchen-im-web.de offers the data via a public API at https://kirchen-im-web.de/api/ which returns all the data on the selected churches in JSON format. Even if there is only one result for the query, the data is returned as a list.

GET /api/churches/

Per default, the whole data is returned in JSON. Parameters can be used to reduce the number of entries which are returned.

Example: A call to https://kirchen-im-web.de/api/churches/?name=test only returns data of the churches whose name contains the string test.

Supported parameters:

• ids (optional): entry ids (multiple ids can be separated by comma)
• parent (optional): only children of the given parent id (options allow to include the parent itself and grandchildren)
• name (optional): the substring of the name
• postalCode (optional): the postal code
• city (optional): the substring of the city
• country (optional): the country code (e. g. DE for Germany). Possible values: see $countries variable in the configuration file
• denomination (optional): the denomination. Possible values: see $denominations variable in the configuration file
• type (optional): the type. Possible values: see $types variable in the configuration file
• hasWebsiteType (optional): the website type. Possible values: see $websites variable in the configuration file
• options=includeSelf,recursive (optional):
  • If parent is given and options contains childrenRecursive, the grandchildren are also included in the response.
  • If parent is given and options contains includeSelf, the parent is included in the response.

GET /api/churches/{id}/

The data of the church with the given id is returned in JSON. The entry id is the number in the URL of the details page.

GET /api/churches/{id}/children/

Returns the (direct) children of the church with the given id in JSON.

GET /api/churches/{id}/followers/

Returns the follower history for the social networks of the church in csv or JSON.

• type: csv or JSON (default)

How to develop

Requirements

• Apache 2.4+
• PHP 8.3+
• MySQL database
• npm 9+
• Composer 2+

Setup

• Clone the Git repository.
• Install the dependencies via composer install and npm install.
• Run npm run watch to automatically compile *.scss to *.css and *.js to *.min.js whenever the file is changed.
• Create a database and create the tables with database-scheme.sql.
• Create a config/config.php with the database credentials and valid API keys/secrets (cp. config/config.sample.php).

Code Style Guidelines

• CSS: recommended configuration for stylelint
  • npm run csCSS to run a check for compliance with the guidelines
  • npm run csfixCSS applies fixes for violations automatically.
• JavaScript: JavaScript Standard Style, checked by eslint
  • npm run csJS to run a check for compliance with the guidelines
  • npm run csfixJS applies fixes for violations automatically.
• PHP: PSR12
  • composer csPHP to run a check for compliance with the guidelines
  • composer fixPHP applies fixes for violations automatically.

To run all checks, use composer cs.

Used programming languages and libraries

• HTML and CSS, based on Bootstrap
• PHP with libraries Facebook Graph SDK, Instagram PHP Scraper, OpenCage API, Slim, Symphony Translations, Twig and twitter-api-php
• JavaScript, especially the libraries Highcharts, Leaflet and tablesort

How to deploy

• Run npm run production.
• Run composer install --optimize-autoloader --no-dev.
• Upload the following to the production server:
  • the directories config, public, src, resources, vendor, and
  • the file cron.php.
• Create empty directories cache and data.