FEAT: Update README (#17)

# Changelog

## DX: CI/CD
- added prepush composer check

## FEAT: DevOps
- fixed lint workflow
- fixed composer scripts

## FEAT: README
- updated README

.github/workflows/shared-lint.yml

@@ -23,6 +23,8 @@ jobs:
     steps:
       - name: "Checkout"
         uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event_name == 'pull_request_target' && github.event.pull_request.head.sha || github.sha }} # must validate user permissions PRIOR to checkout ⚠️
       - name: "Setup PHP"
         uses: shivammathur/setup-php@v2
         with:

.github/workflows/shared-test.yml

@@ -20,30 +20,7 @@ on:
         required: true
 
 jobs:
-  validate-user-permissions:
-    runs-on: ubuntu-latest
-    name: "Validate User Permissions"
-    steps:
-      - name: "Get user permissions"
-        id: userPermissions
-        uses: actions-cool/check-user-permission@v2
-        with:
-          require: "write"
-          username: ${{ github.triggering_actor }}
-      - name: "Check user permissions"
-        if: steps.userPermissions.outputs.check-result == 'false'
-        run: |
-          echo "${{ github.triggering_actor }} does not have 'write' permission on this repo."
-          echo "Originally triggered by ${{ github.actor }}"
-          exit 1
-      - name: "Audit: user permissions"
-        run: |
-          echo "Audit: Execution by ${{ github.triggering_actor }} with ${{ steps.userPermissions.outputs.user-permission }} permissions"
-
-
   test:
-    needs:
-      - validate-user-permissions
     env:
       GEONAMES_USERNAME: ${{ secrets.geonames-username }}
     strategy:

.github/workflows/validate.yml

@@ -24,9 +24,31 @@ jobs:
         uses: WyriHaximus/github-action-composer-php-versions-in-range@v1
 
 
+  validate-user-permissions:
+    runs-on: ubuntu-latest
+    name: "Validate User Permissions"
+    steps:
+      - name: "Get user permissions"
+        id: userPermissions
+        uses: actions-cool/check-user-permission@v2
+        with:
+          require: "write"
+          username: ${{ github.triggering_actor }}
+      - name: "Check user permissions"
+        if: steps.userPermissions.outputs.check-result == 'false'
+        run: |
+          echo "${{ github.triggering_actor }} does not have 'write' permission on this repo."
+          echo "Originally triggered by ${{ github.actor }}"
+          exit 1
+      - name: "Audit: user permissions"
+        run: |
+          echo "Audit: Execution by ${{ github.triggering_actor }} with ${{ steps.userPermissions.outputs.user-permission }} permissions"
+
+
   lint:
     needs:
       - get-php-info
+      - validate-user-permissions
     name: "Lint"
     uses: "./.github/workflows/shared-lint.yml"
     with:
@@ -38,6 +60,7 @@ jobs:
   test:
     needs:
       - get-php-info
+      - validate-user-permissions
       - lint
     name: "Test"
     uses: "./.github/workflows/shared-test.yml"

README.md

@@ -47,10 +47,27 @@ $country_languages = $country->languages;
 
 ## Client Options
 
-### Change API URL
+Supported client options:
+
+1. `username`: GeoNames username.
+2. `token`?: GeoNames token (i.e. premium user key).
+3. `api_url`?: URL of the GeoNames web service.
+4. `connect_timeout`?: HTTP Client connection timeout. The number of seconds to
+   wait while trying to connect to a server (default `0`, wait indefinitely).
+5. `fallback_api_url`: COMING SOON.
+6. `fallback_api_url_trigger_count`: COMING SOON.
+
+### Example: Providing options during instantiation
 
 ```php
-$g = new GeoNamesClient('username', null, ['apiUrl' => 'https://custom-premium.geonames.org']);
+$g = new GeoNamesClient('username', '', ['api_url' => 'https://custom-premium.geonames.org']);
+```
+
+### Example: Changing options during runtime
+
+```php
+$g = new GeoNamesClient('username');
+$g->setOptions(['api_url' => 'https://custom-premium.geonames.org'])
 ```
 
 ## Why?

composer.json

@@ -19,7 +19,8 @@
     "aternus:test": "phpunit --testdox"
   },
   "scripts-descriptions": {
-    "aternus:style": "Validate the coding style of the library.",
+    "aternus:style-check": "Validate the coding style of the library.",
+    "aternus:style-fix": "Adjust the code according to the coding style of the library.",
     "aternus:test": "Test the code of the library."
   },
   "homepage": "https://github.com/Aternus/geonames-client",

run-prepush.sh

@@ -7,6 +7,8 @@ while ! docker compose logs php7 | grep -m 1 "php7 has started"; do
     sleep 1
 done
 
+docker compose exec php7 composer validate --strict
+
 docker compose exec php7 composer aternus:style-fix
 
 docker compose exec php7 composer aternus:style-check