#!/usr/bin/env php
<?php

/**
 * This is the Drush "finder" script, which is one part of the
 * Drush dispatching chain.  This is the script that
 * should appear in your global $PATH, or, if using Composer
 * (as usually the case), will be found in your vendor/bin directory.
 *
 *
 * - Never copy this script to your site root. Copy examples/drush instead.
 *
 * - Never copy this script to a directory other than its install directory.
 * Symlink to it instead.
 *
 *
 * OVERVIEW OF DRUSH FINDER / WRAPPER / LAUNCHER SCRIPTS
 *
 * When the user types "drush", up to three scripts might be
 * involved in the initial launch:
 *
 *   "drush finder" -> "drush wrapper" -> "drush launcher".
 *
 * Brief description of each:
 *
 *  - Drush finder:   Finds the right Drush script and calls it.
 *  - Drush wrapper:  Contains user customizations to options.
 *  - Drush launcher: Excutes drush.php.
 *
 * A full explanation of each script follows.
 *
 *
 * DRUSH FINDER
 *
 * - The "drush" script on the user's global $PATH
 * - It's goal is to find the correct site-local Drush to run.
 *
 * The Drush finder will locate the correct site-local Drush to use
 * by examining:
 *
 *   a) The --root option
 *   b) The site set via `drush site set` in the current terminal
 *   c) The cwd
 *
 * If no site-local Drush is found, then the global Drush will be
 * used.  The Drush finder assumes that the global Drush is the
 * "Drush launcher" found in the same directory as the Drush finder itself.
 *
 * If a site-local Drush is found, then the Drush finder will call
 * either the "Drush wrapper", if it exists, or the "Drush launcher" if
 * there is no wrapper script.
 *
 *
 * DRUSH WRAPPER
 *
 * - The drush.wrapper script that the user optionally copies and edits.
 * - Its goal is to allow the user to add options when --local is in use
 *
 * The Drush "wrapper" is found at examples/drush.wrapper, and may optionally
 * be copied to __ROOT__ by the user.  It may be named either
 * "drush" or "drush.wrapper".  It will call the "Drush launcher"
 * for the same site that it is located in.  It adds the --local flag; the
 * user is encouraged to add other options to the "Drush wrapper", e.g. to set
 * the location where aliases and global commandfiles can be found.
 * The Drush "finder" script always calls the "Drush wrapper" if it exists;
 * however, if the user does not want to customize the early options of
 * the site-local Drush (site-alias locations, etc.), then the wrapper does not
 * need to be used.
 *
 *
 * DRUSH LAUNCHER
 *
 * - The "drush.launcher" script in vendor/bin
 * - The bash script formerly called "drush"
 *
 * The "Drush launcher" is the traditional script that identifies PHP and
 * sets up to call drush.php.  It is called by the "Drush wrapper", or
 * directly by the "Drush launcher" if there is no "Drush wrapper" in use.
 *
 *
 * LOCATIONS FOR THESE SCRIPTS
 *
 *   "Drush finder"   :  __ROOT__/vendor/bin/drush           (composer install)
 *                       __DRUSH__/drush                     (source)
 *
 *   "Drush wrapper"  :  __ROOT__/drush                      (copied by user)
 *                       __DRUSH__/examples/drush.wrapper    (source)
 *
 *   "Drush launcher" :  __ROOT__/vendor/bin/drush.launcher  (composer install)
 *                       __DRUSH__/drush.launcher            (source)
 *
 *
 * BACKEND CALL DISPATCHING
 *
 * Backend calls are typically set up to call the "drush" script in the $PATH,
 * or perhaps some might call __ROOT__/vendor/bin/drush directly, by way
 * of the "drush-script" element in a site alias.  In either event, this is
 * the "drush finder" script.
 *
 * The backend call will always set --root.  The "Drush finder" script
 * always favors the site-local Drush stored with the site indicated by the
 * --root option, if it exists.  If there is no site-local Drush, then the
 * "Drush finder" will behave as usual (i.e., it will end up calling the
 * "Drush launcher" located next to it).
 *
 * This should always get you the correct "Drush" for local and remote calls.
 * Note that it is also okay for aliases to specify a path directly to
 * drush.launcher, in instances where it is known that a recent version of
 * Drush is installed on the remote end.
 */

if (!function_exists("drush_startup")) {
  include __DIR__ . '/includes/startup.inc';
}
drush_startup($argv);