Composer自动加载失效求助：无法加载OneLogin\Saml2类

问题背景 #

首次用Composer管理自有项目依赖，composer.json配置正确，执行composer update已成功拉取onelogin/php-saml及其依赖、生成autoload.php，但调用OneLogin\Saml2\Settings时提示类找不到，调试发现ClassLoader路径配置正确，手动引入文件可正常运行。

排查与解决步骤 #

• 确认autoload.php路径正确性
  替换相对路径为绝对路径，避免工作目录差异导致的路径问题：

  require_once __DIR__ . '/vendor/autoload.php';
  

  可通过echo getcwd();输出当前脚本的工作目录，对比vendor文件夹的实际位置，确保路径匹配。

• 重新生成自动加载映射文件
  执行Composer命令强制更新自动加载缓存，生成优化后的类映射：

  composer dump-autoload -o
  

• 检查包文件结构与命名规范
  进入vendor/onelogin/php-saml/src/OneLogin/Saml2/目录，确认Settings.php文件存在，且文件内的类声明符合规范：

  namespace OneLogin\Saml2;
  
  class Settings {
      // ...
  }
  

  注意Linux系统下文件名和类名大小写严格对应，需确保Settings.php与类名Settings大小写一致。

• 排查自定义自动加载冲突
  检查项目中是否存在其他自定义的spl_autoload_register逻辑，确保Composer的自动加载是最后注册的，避免被其他自动加载逻辑覆盖。

• 验证PHP版本兼容性
  onelogin/php-saml 4.1.*要求PHP版本 >= 7.4，执行php -v确认当前PHP版本符合要求，版本过低会导致类无法正常加载。

内容的提问来源于stack exchange，提问作者Will Martin