v1.5.0 (#52)

README.md

@@ -1 +1,3 @@
-# churchsuite-feeds
+# Church Suite Feeds
+
+Links data exported from [Church Suite](https://www.churchsuite.com) with an online database, to provide calendar and rota feeds, including information about teaching series, Bible readings, service names and types.  Also provides a monthly prayer calendar of church members, and an optional daily Bible reading plan.

VERSION

@@ -1 +1 @@
-1.4.9
+1.5.0

VERSION_MINOR

@@ -1 +1 @@
-1.3
+1.5

config-sample.yml

@@ -44,7 +44,7 @@ rota:
   bible_version: 'NIVUK'
   default_days: 28
   default_length: 'PT90M'
-  roles:
+  ministries:
     - { name: 'Intercessions', desc: 'Intercessor', abbv: 'I' }
     - { name: 'Preacher', abbv: 'Pr' }
     - { name: 'President', abbv: 'Ps' }

src/classes/config/config-rota-role.class.php → src/classes/config/config-rota-ministry.class.php

@@ -7,33 +7,33 @@
 
 App::check();
 
-class Config_Rota_Role
+class Config_Rota_Ministry
 {
     /**
-     * The Church Suite role name (e.g. 'Readings').
+     * The Church Suite ministry name (e.g. 'Readings').
      *
      * @var string
      */
     public readonly string $name;
 
     /**
-     * Optional role name override (e.g. 'Reader').
+     * Optional ministry name override (e.g. 'Reader').
      *
      * @var string
      */
     public readonly ?string $description;
 
     /**
-     * Optional role name abbreviation (e.g. 'R').
+     * Optional ministry name abbreviation (e.g. 'R').
      *
      * @var string
      */
     public readonly ?string $abbreviation;
 
     /**
-     * Get values from a rota configuration role array.
+     * Get values from a rota configuration ministries array.
      *
-     * @param array $config             Rota configuration roles array.
+     * @param array $config             Rota configuration ministries array.
      * @return void
      */
     public function __construct(array $config)

src/classes/config/config-rota.class.php

@@ -32,11 +32,11 @@ class Config_Rota
     public readonly DateInterval $default_length;
 
     /**
-     * Array of roles on this rota, with override descriptions and abbreviations.
+     * Array of ministries on this rota, with override descriptions and abbreviations.
      *
-     * @var Config_Rota_Role[]
+     * @var Config_Rota_Ministry[]
      */
-    public readonly array $roles;
+    public readonly array $ministries;
 
     /**
      * Get values from rota configuration array.
@@ -50,10 +50,10 @@ public function __construct(array $config)
         $this->default_days = Arr::get($config, "default_days", 28);
         $this->default_length = new DateInterval(Arr::get($config, "default_length", "PT60M"));
 
-        $roles = array();
-        foreach (Arr::get($config, "roles") as $role) {
-            $roles[] = new Config_Rota_Role($role);
+        $ministries = array();
+        foreach (Arr::get($config, "ministries") as $ministry) {
+            $ministries[] = new Config_Rota_Ministry($ministry);
         }
-        $this->roles = $roles;
+        $this->ministries = $ministries;
     }
 }

src/classes/rota/builder.class.php

@@ -14,9 +14,9 @@
 class Builder
 {
     /**
-     * Character used to join roles in service summary descriptions.
+     * Character used to join ministries in service summary descriptions.
      */
-    private const ROLE_JOIN = "/";
+    private const MINISTRY_JOIN = "/";
 
     /**
      * Array of days of the week, starting with Sunday, numbered to match DateTimeImmutable format 'N'
@@ -84,7 +84,7 @@ public static function build_combined_rota(Lectionary $lectionary, array $servic
                     main_reading: $lectionary_service?->main_reading,
                     additional_reading: $lectionary_service?->additional_reading,
                     psalms: $lectionary_service?->psalms ?: array(),
-                    roles: $rota_service->roles
+                    ministries: $rota_service->ministries
                 );
             }
 
@@ -113,11 +113,11 @@ public static function get_day(int $num): null|string
     }
 
     /**
-     * Generate an event summary for a service, including role indicators for the specified person.
+     * Generate an event summary for a service, including ministry indicators for the specified person.
      *
      * @param Combined_Service $service     Service object.
      * @param null|string $person           Selected person.
-     * @return string                       Service name with role indicators.
+     * @return string                       Service name with ministry indicators.
      */
     public static function get_summary(Combined_Service $service, ?string $person = null): string
     {
@@ -129,39 +129,39 @@ public static function get_summary(Combined_Service $service, ?string $person =
             return $summary;
         }
 
-        // look for certain roles
-        $roles = array();
-        foreach ($service->roles as $service_role) {
-            foreach ($service_role->people as $p) {
+        // look for certain ministries
+        $ministries = array();
+        foreach ($service->ministries as $service_ministry) {
+            foreach ($service_ministry->people as $p) {
                 if (str_starts_with($p, $person)) {
-                    $roles[] = $service_role->abbreviation;
+                    $ministries[] = $service_ministry->abbreviation;
                 }
             }
         }
 
-        // filter out blank roles
-        $filtered = array_filter($roles);
+        // filter out blank ministries
+        $filtered = array_filter($ministries);
 
-        // if there are no roles, return the summary
-        // if there are roles, but filtered is empty, that means there are roles
+        // if there are no ministries, return the summary
+        // if there are ministries, but filtered is empty, that means there are ministries
         // but they don't have abbreviations defined so add an asterisk instead
-        if (count($roles) == 0) {
+        if (count($ministries) == 0) {
             return $summary;
         } elseif (count($filtered) == 0) {
             return sprintf("%s (*)", $summary);
         }
 
-        // sort filtered roles and add to summary
+        // sort filtered ministries and add to summary
         sort($filtered);
-        return sprintf("%s (%s)", $summary, join(self::ROLE_JOIN, $filtered));
+        return sprintf("%s (%s)", $summary, join(self::MINISTRY_JOIN, $filtered));
     }
 
     /**
-     * Generate an event description for a service, including lectionary / teaching info and roles.
+     * Generate an event description for a service, including lectionary / teaching info and ministries.
      *
      * @param Combined_Day $day         Lectionary day information.
      * @param Combined_Service $service Service object.
-     * @param bool $include_people      If true, people and roles will be added to the description.
+     * @param bool $include_people      If true, people and ministries will be added to the description.
      * @param string $separator         Line separator.
      * @return string                   Event description.
      */
@@ -212,11 +212,11 @@ public static function get_description(
             $description[] = "";
         }
 
-        // add roles
-        if ($include_people && $service->roles) {
-            $description[] = "= Roles =";
-            foreach ($service->roles as $name => $service_role) {
-                $description[] = sprintf("%s: %s", $name, join(", ", $service_role->people));
+        // add ministries
+        if ($include_people && $service->ministries) {
+            $description[] = "= Ministries =";
+            foreach ($service->ministries as $name => $service_ministry) {
+                $description[] = sprintf("%s: %s", $name, join(", ", $service_ministry->people));
             }
             $description[] = "";
         }

src/classes/rota/combined-service.class.php

@@ -22,7 +22,7 @@ class Combined_Service
      * @param null|string $main_reading         Optional main reading.
      * @param null|string $additional_reading   Optional additional reading.
      * @param array $psalms                     Optional psalms.
-     * @param Service_Role[] $roles             Roles from the rota.
+     * @param Service_Ministry[] $ministries    Ministries from the rota.
      * @return void
      */
     public function __construct(
@@ -36,7 +36,7 @@ public function __construct(
         public readonly ?string $main_reading,
         public readonly ?string $additional_reading,
         public readonly array $psalms,
-        public readonly array $roles
+        public readonly array $ministries
     ) {
     }
 }

src/classes/rota/filters/person-filter.class.php

@@ -11,12 +11,12 @@
 class Person_Filter implements Filter
 {
     /**
-     * Returns true if the person ($value) is doing one of the roles.
+     * Returns true if the person ($value) is doing one of the ministries.
      *
      * @param Lectionary $lectionary    Lectionary object
      * @param Service $service          Service object.
      * @param string $value             A person's name.
-     * @return bool                     True if person ($value) is doing one of the roles in the service.
+     * @return bool                     True if person ($value) is doing one of the ministries in the service.
      */
     public function apply(Lectionary $lectionary, Service $service, string $value) : bool
     {
@@ -25,16 +25,16 @@ public function apply(Lectionary $lectionary, Service $service, string $value) :
             return true;
         }
 
-        // loop through each role - the first time the person is matched, return true
-        foreach ($service->roles as $service_role) {
-            foreach ($service_role->people as $person) {
+        // loop through each ministry - the first time the person is matched, return true
+        foreach ($service->ministries as $service_ministry) {
+            foreach ($service_ministry->people as $person) {
                 if (str_starts_with($person, $value)) {
                     return true;
                 }
             }
         }
 
-        // if we get here the person has not matched any of the roles so return false
+        // if we get here the person has not matched any of the ministries so return false
         return false;
     }
 }

src/classes/rota/rota.class.php

@@ -139,8 +139,8 @@ public function apply_filters(array $filters, Lectionary $lectionary): array
         $series_filter = new Series_Filter();
 
         foreach ($this->services as $service) {
-            // only include services that have roles with assigned people
-            $include = count($service->roles) > 0;
+            // only include services that have ministries with assigned people
+            $include = count($service->ministries) > 0;
 
             // apply person filter
             $include = $include && $person_filter->apply($lectionary, $service, Arr::get($filters, "person", ""));

src/classes/rota/service-role.class.php → src/classes/rota/service-ministry.class.php

@@ -6,13 +6,13 @@
 
 App::check();
 
-class Service_Role
+class Service_Ministry
 {
     /**
-     * Create Service_Role object.
+     * Create Service_Ministry object.
      *
-     * @param ?string $abbreviation             Role abbreviation.
-     * @param string[] $people                  Names of the people with this role.
+     * @param ?string $abbreviation             Ministry abbreviation.
+     * @param string[] $people                  Names of the people with this ministry.
      */
     public function __construct(
         public readonly ?string $abbreviation,

src/classes/rota/service.class.php

@@ -2,11 +2,9 @@
 
 namespace Feeds\Rota;
 
-use DateInterval;
 use DateTimeImmutable;
 use Feeds\App;
 use Feeds\Config\Config as C;
-use Feeds\Helpers\Arr;
 
 App::check();
 
@@ -20,11 +18,11 @@ class Service
     public readonly DateTimeImmutable $start;
 
     /**
-     * The roles and people assigned to this service.
+     * The ministries and people assigned to this service.
      *
-     * @var Service_Role[]              Array key is role name / description.
+     * @var Service_Ministry[]              Array key is ministry name / description.
      */
-    public readonly array $roles;
+    public readonly array $ministries;
 
     /**
      * All the people in the current service.
@@ -50,14 +48,14 @@ public function __construct(array $header_row, array $row)
         // get the start date and time as a timestamp
         $this->start = DateTimeImmutable::createFromFormat(C::$formats->csv_import_datetime, sprintf("%s%s", $data["Date"], $data["Time"]), C::$events->timezone);
 
-        // get the roles
-        $this->roles = $this->get_roles($data);
+        // get the ministries
+        $this->ministries = $this->get_ministries($data);
 
         // get all the people involved in this service
         $people = array();
-        foreach ($this->roles as $service_roles) {
+        foreach ($this->ministries as $service_ministries) {
             // remove extra information and merge arrays
-            $people = array_merge(preg_replace("/ \(.*\)/", "", $service_roles->people), $people);
+            $people = array_merge(preg_replace("/ \(.*\)/", "", $service_ministries->people), $people);
         }
 
         // sort alphabetically and remove duplicates
@@ -66,39 +64,39 @@ public function __construct(array $header_row, array $row)
     }
 
     /**
-     * Get all supported roles and the people assigned to each one, and add to $this->roles.
+     * Get all supported ministries and the people assigned to each one, and add to $this->ministries.
      *
      * @param array $data               Associative array of service data.
-     * @return Service_Role[]           Associative array of roles.
+     * @return Service_Ministry[]       Associative array of ministries.
      */
-    private function get_roles(array $data): array
+    private function get_ministries(array $data): array
     {
-        // create empty roles array
-        $roles = array();
-        foreach ($data as $rota_role => $people) {
+        // create empty ministries array
+        $ministries = array();
+        foreach ($data as $rota_ministry => $people) {
             // skip if no-one is assigned
             if (!$people) {
                 continue;
             }
 
-            // add role if it is in the supported array
-            foreach (C::$rota->roles as $supported_role) {
-                if (str_starts_with($rota_role, $supported_role->name)) {
-                    $name = $supported_role->description ?: $supported_role->name;
-                    $roles[$name] = new Service_Role($supported_role->abbreviation, $this->sanitise_people($people));
+            // add ministry if it is in the supported array
+            foreach (C::$rota->ministries as $supported_ministry) {
+                if (str_starts_with($rota_ministry, $supported_ministry->name)) {
+                    $name = $supported_ministry->description ?: $supported_ministry->name;
+                    $ministries[$name] = new Service_Ministry($supported_ministry->abbreviation, $this->sanitise_people($people));
                 }
             }
         }
 
-        // sort and return roles
-        ksort($roles);
-        return $roles;
+        // sort and return ministries
+        ksort($ministries);
+        return $ministries;
     }
 
     /**
      * Sanitise the input, removing various bits of unnecessary information provided by Church Suite.
      *
-     * @param string $people            List of people assigned to this role (and other bits of information).
+     * @param string $people            List of people assigned to this ministry (and other bits of information).
      * @return string[]                 Array of people's names.
      */
     private function sanitise_people(string $people): array