Merge pull request #1 from stellarwp/feature/config

Add a config class to provide some customizability

.github/workflows/tests-php.yml

@@ -15,14 +15,14 @@ jobs:
           fetch-depth: 1000
           submodules: recursive
       # ------------------------------------------------------------------------------
-      # Checkout tric
+      # Checkout slic
       # ------------------------------------------------------------------------------
-      - name: Checkout tric
+      - name: Checkout slic
         uses: actions/checkout@v2
         with:
-          repository: the-events-calendar/tric
+          repository: stellarwp/slic
           ref: main
-          path: tric
+          path: slic
           fetch-depth: 1
       # ------------------------------------------------------------------------------
       # Prepare our composer cache directory
@@ -39,35 +39,35 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-composer-
       # ------------------------------------------------------------------------------
-      # Initialize tric
+      # Initialize slic
       # ------------------------------------------------------------------------------
-      - name: Set up tric env vars
+      - name: Set up slic env vars
         run: |
-          echo "TRIC_BIN=${GITHUB_WORKSPACE}/tric/tric" >> $GITHUB_ENV
-          echo "TRIC_WP_DIR=${GITHUB_WORKSPACE}/tric/_wordpress" >> $GITHUB_ENV
-          echo "TRIC_WORDPRESS_DOCKERFILE=Dockerfile.base" >> $GITHUB_ENV
-      - name: Set run context for tric
-        run: echo "TRIC=1" >> $GITHUB_ENV && echo "CI=1" >> $GITHUB_ENV
+          echo "SLIC_BIN=${GITHUB_WORKSPACE}/slic/slic" >> $GITHUB_ENV
+          echo "SLIC_WP_DIR=${GITHUB_WORKSPACE}/slic/_wordpress" >> $GITHUB_ENV
+          echo "SLIC_WORDPRESS_DOCKERFILE=Dockerfile.base" >> $GITHUB_ENV
+      - name: Set run context for slic
+        run: echo "SLIC=1" >> $GITHUB_ENV && echo "CI=1" >> $GITHUB_ENV
       - name: Start ssh-agent
         run: |
           mkdir -p "${HOME}/.ssh";
           ssh-agent -a /tmp/ssh_agent.sock;
       - name: Export SSH_AUTH_SOCK env var
         run: echo "SSH_AUTH_SOCK=/tmp/ssh_agent.sock" >> $GITHUB_ENV
-      - name: Set up tric for CI
+      - name: Set up slic for CI
         run: |
           cd ${GITHUB_WORKSPACE}/..
-          ${TRIC_BIN} here
-          ${TRIC_BIN} interactive off
-          ${TRIC_BIN} build-prompt off
-          ${TRIC_BIN} build-subdir off
-          ${TRIC_BIN} xdebug off
-          ${TRIC_BIN} debug on
-          ${TRIC_BIN} info
-          ${TRIC_BIN} config
+          ${SLIC_BIN} here
+          ${SLIC_BIN} interactive off
+          ${SLIC_BIN} build-prompt off
+          ${SLIC_BIN} build-subdir off
+          ${SLIC_BIN} xdebug off
+          ${SLIC_BIN} debug on
+          ${SLIC_BIN} info
+          ${SLIC_BIN} config
       - name: Set up StellarWP DB
         run: |
-          ${TRIC_BIN} use db
-          ${TRIC_BIN} composer install --ignore-platform-reqs
+          ${SLIC_BIN} use db
+          ${SLIC_BIN} composer install --ignore-platform-reqs
       - name: Run suite wpunit
-        run: ${TRIC_BIN} run ${{ matrix.suite }} --ext DotReporter
+        run: ${SLIC_BIN} run ${{ matrix.suite }} --ext DotReporter

README.md

@@ -18,6 +18,10 @@ composer require stellarwp/db
 
 ## Table of contents
 
+- [Quick start](#quick-start)
+
+- [Configuration](#configuration)
+
 - [DB](#db)
 
 - [Select statements](#select-statements)
@@ -65,6 +69,50 @@ composer require stellarwp/db
     - [Min](#min)
     - [Max](#max)
 
+## Quick start
+
+Getting up and running with this library is easy. You'll want to initialize the `DB` class. Doing so during the `plugins_loaded` action is a reasonable location, though you can do it anywhere that feels appropriate.
+
+_For this example and all future ones, let's assume you have [included this library with Strauss](https://github.com/stellarwp/global-docs/blob/main/docs/strauss-setup.md) and your project's namespace is `Boom\Shakalaka`._
+
+```php
+use Boom\Shakalaka\StellarWP\DB\DB;
+
+add_action( 'plugins_loaded', function() {
+	DB::init();
+}, 0 );
+```
+
+The two main classes that make up the core of this library are the `DB` class and the `QueryBuilder` class. Here are their namespaces:
+
+```php
+# For DB, it is "StellarWP\DB\DB", but with your namespace prefix it'll be:
+use Boom\Shakalaka\StellarWP\DB\DB;
+
+# For QueryBuilder, it is "StellarWP\DB\QueryBuilder\QueryBuilder", but with your namespace prefix it'll be:
+use Boom\Shakalaka\StellarWP\DB\QueryBuilder\QueryBuilder;
+```
+
+## Configuration
+
+This library provides default hooks and exceptions, however, if you have additional needs for your own application, you can override one or both via the `StellarWP\DB\Config` class:
+
+```php
+use Boom\Shakalaka\StellarWP\DB\Config;
+
+// Ensure hooks are prefixed with your project's prefix.
+Config::setHookPrefix( 'boom_shakalaka' );
+
+// Use your own exception class rather than the default Database\Exceptions\DatabaseQueryException class.
+Config::setDatabaseQueryException( 'MyCustomException' );
+
+// Fetch the hook prefix.
+$prefix = Config::getHookPrefix();
+
+// Fetch the database query exception class.
+$class = Config::getDatabaseQueryException();
+```
+
 ## DB
 
 `DB` class is a static decorator for the `$wpdb` class, but it has a few methods that are exceptions to that.

codeception.tric.yml → codeception.slic.yml

@@ -1,3 +1,3 @@
 params:
   # read dynamic configuration parameters from the .env file
-  - .env.testing.tric
+  - .env.testing.slic

composer.json

@@ -20,9 +20,7 @@
     }
   ],
   "minimum-stability": "stable",
-  "require": {
-    "lucatume/di52": "^3.0"
-  },
+  "require": {},
   "require-dev": {
     "codeception/module-asserts": "^1.0",
     "codeception/module-cli": "^1.0",