hphp/runtime/base/autoload-map.h

   1 /*
   2    +----------------------------------------------------------------------+
   3    | HipHop for PHP                                                       |
   4    +----------------------------------------------------------------------+
   5    | Copyright (c) 2010-present Facebook, Inc. (http://www.facebook.com)  |
   6    +----------------------------------------------------------------------+
   7    | This source file is subject to version 3.01 of the PHP license,      |
   8    | that is bundled with this package in the file LICENSE, and is        |
   9    | available through the world-wide-web at the following url:           |
  10    | http://www.php.net/license/3_01.txt                                  |
  11    | If you did not receive a copy of the PHP license and are unable to   |
  12    | obtain it through the world-wide-web, please send a note to          |
  13    | license@php.net so we can mail you a copy immediately.               |
  14    +----------------------------------------------------------------------+
  15 */
  16
  17 #pragma once
  18
  19 #include <optional>
  20 #include <vector>
  21
  22 #include "hphp/runtime/base/type-string.h"
  23 #include "hphp/util/assertions.h"
  24
  25 namespace folly {
  26   struct dynamic;
  27 }
  28
  29 namespace HPHP {
  30
  31 struct Variant;
  32
  33 struct AutoloadMap {
  34
  35   enum class Result {
  36     Failure,
  37     Success,
  38     StopAutoloading,
  39     RetryAutoloading
  40   };
  41
  42   enum class KindOf {
  43     Type,
  44     Function,
  45     Constant,
  46     TypeAlias,
  47   };
  48
  49   virtual ~AutoloadMap() = default;
  50
  51   /**
  52    * Block until the AutoloadMap is up-to-date.
  53    *
  54    * May throw an exception if updating failed.
  55    */
  56   virtual void ensureUpdated() {
  57   }
  58
  59   /**
  60    * True iff this AutoloadMap knows which files contain which symbols without
  61    * needing to query userland Hack code. If we're using a native AutoloadMap,
  62    * we'll be able to use any symbol when the very first line of Hack code is
  63    * run.
  64    */
  65   virtual bool isNative() const noexcept = 0;
  66
  67   /**
  68    * Given the name of a type and the kind of type we're looking for,
  69    * return the absolute path of the file defining that type.
  70    *
  71    * Return None if the file is defined in zero places or more than
  72    * one place.
  73    */
  74   std::optional<String> getFile(KindOf kind,
  75                                   const String& typeName) {
  76     switch (kind) {
  77       case AutoloadMap::KindOf::Type:
  78         return getTypeFile(typeName);
  79       case AutoloadMap::KindOf::Function:
  80         return getFunctionFile(typeName);
  81       case AutoloadMap::KindOf::Constant:
  82         return getConstantFile(typeName);
  83       case AutoloadMap::KindOf::TypeAlias:
  84         return getTypeAliasFile(typeName);
  85     }
  86     not_reached();
  87   }
  88
  89   Array getSymbols(KindOf kind,
  90                    const String& path) {
  91     switch (kind) {
  92       case AutoloadMap::KindOf::Type:
  93         return getFileTypes(path);
  94       case AutoloadMap::KindOf::Function:
  95         return getFileFunctions(path);
  96       case AutoloadMap::KindOf::Constant:
  97         return getFileConstants(path);
  98       case AutoloadMap::KindOf::TypeAlias:
  99         return getFileTypeAliases(path);
 100     }
 101     not_reached();
 102   }
 103
 104   /**
 105    * Get all filepaths known to the autoloader at this point in time.
 106    *
 107    * Each path must be an absolute path with all symlinks dereferenced.
 108    */
 109   virtual Array getAllFiles() const = 0;
 110
 111   /**
 112    * Map symbols to files
 113    */
 114   virtual std::optional<String> getTypeFile(
 115       const String& typeName) = 0;
 116   virtual std::optional<String> getFunctionFile(
 117       const String& functionName) = 0;
 118   virtual std::optional<String> getConstantFile(
 119       const String& constantName) = 0;
 120   virtual std::optional<String> getTypeAliasFile(
 121       const String& typeAliasName) = 0;
 122
 123   /**
 124    * Map path to symbols
 125    */
 126   virtual Array getFileTypes(const String& path) = 0;
 127   virtual Array getFileFunctions(const String& path) = 0;
 128   virtual Array getFileConstants(const String& path) = 0;
 129   virtual Array getFileTypeAliases(const String& path) = 0;
 130
 131   virtual bool canHandleFailure() const = 0;
 132   virtual Result handleFailure(KindOf kind, const String& className,
 133                                const Variant& err) const = 0;
 134 };
 135
 136 /**
 137  * An AutoloadMap which can also return data not directly related to
 138  * autoloading.
 139  */
 140 struct FactsStore : public AutoloadMap {
 141
 142   virtual ~FactsStore() = default;
 143
 144   /**
 145    * Return the correctly-capitalized name of `type`.
 146    *
 147    * Return `null` if `type` is not defined, or if it is defined in more than
 148    * one file.
 149    */
 150   virtual Variant getTypeName(const String& type) = 0;
 151
 152   /**
 153    * Return whether the given type is a class, enum, interface, or trait.
 154    *
 155    * Return `null` if given none of the above.
 156    */
 157   virtual Variant getKind(const String& type) = 0;
 158
 159   /**
 160    * Return true iff the type cannot be constructed.
 161    */
 162   virtual bool isTypeAbstract(const String& type) = 0;
 163
 164   /**
 165    * Return true iff no other type can inherit from this type.
 166    */
 167   virtual bool isTypeFinal(const String& type) = 0;
 168
 169   /**
 170    * Return all types in the repo which the given type extends.
 171    */
 172   virtual Array getBaseTypes(
 173       const String& derivedType, const Variant& filters) = 0;
 174
 175   /**
 176    * Return all types in the repo which extend the given type.
 177    */
 178   virtual Array getDerivedTypes(
 179       const String& baseType, const Variant& filters) = 0;
 180
 181   /**
 182    * Return all types in the repo which transitively extend the given type.
 183    */
 184   virtual Array getTransitiveDerivedTypes(
 185     const String& baseType, const Variant& filters) = 0;
 186
 187   /**
 188    * Return all types decorated with the given attribute, as a
 189    * keyset<classname<mixed>>.
 190    */
 191   virtual Array getTypesWithAttribute(const String& type) = 0;
 192
 193   /**
 194    * Return all attributes decorating the given type.
 195    */
 196   virtual Array getTypeAttributes(const String& type) = 0;
 197
 198   /**
 199    * Return the arguments associated with the given type and attribute, as a
 200    * vec.
 201    *
 202    * If the given type does not have the given attribute, return an empty vec.
 203    */
 204   virtual Array getTypeAttrArgs(const String& type, const String& attr) = 0;
 205
 206   /**
 207    * Return all symbols defined in the repo, as a dict mapping each symbol
 208    * name to the path where the symbol lives in the repo.
 209    *
 210    * If a symbol is defined in more than one path, one of the paths defining the
 211    * symbol will be chosen in an unspecified manner.
 212    */
 213   virtual Array getAllTypes() = 0;
 214   virtual Array getAllFunctions() = 0;
 215   virtual Array getAllConstants() = 0;
 216   virtual Array getAllTypeAliases() = 0;
 217 };
 218
 219 } // namespace HPHP