php-sage/sage

☯ 深入的 PHP 调试助手。

维护者

详细信息

github.com/php-sage/sage

主页

源代码

问题

安装: 13,406

依赖: 9

建议者: 1

安全: 0

星标: 45

关注者: 4

分支: 4

开放问题: 1

v1.7.0 2024-03-07 14:55 UTC

Requires

  • php: >=5.1.0

Requires (Dev)

MIT f124942f122b08aac3295b1699e6d448ba2c9d08

phpdebugdumpvar_dumpdumperjson_decodesagedebug_backtrace

This package is auto-updated.

Last update: 2024-09-02 02:14:44 UTC

README

初看之下，Sage 只是 var_dump() 和 debug_backtrace() 的替代品。

然而，它的功能远不止于此。

Sage 被设计用来超越期望，它智能地处理你抛给它的所有内容，并以最佳方式展示。

如果你能想到如何让它变得更好，请创建一个问题！

要了解 Sage 的突出功能，请跳转到 常见问题解答

安装

composer require php-sage/sage --dev

或者，如果你更喜欢，下载 phar 并简单地

<?php
require 'sage.phar';

sage('Hello, 🌎!');

或者如果你的 PHP 版本不支持这两个，下载最新源代码 并包含 Sage.php

require 'sage-main/Sage.php';

sage('Hello, 🌎!');

使用方法

sage($GLOBALS, $_SERVER); // dump any number of parameters

saged($i); // alias for sage();die;

sage(1); // shortcut for dumping trace

简单的转储

simple mode example

调试回溯

Trace view

保证 ✅

  1. Sage 只需工作 并显示所有可用信息（或在某些情况下，如果内容被截断，这也是清晰的）。

  2. 每个 发布 都经过严格的测试。或者 - 使用具有风险的 dev-main 版本。

  3. 语义版本确保在生产中（例如，报告）使用时没有兼容性中断。

  4. Sage 在过去 >10 年中得到了许多爱和支持以及改进。它在许多真实世界中由许多人使用，经过战斗测试，具有许多其他工具没有的高级功能。

更多酷炫功能

Sage 显示传递的变量名并支持对转储函数调用的前缀。用于对转储输出进行一些常见的即时调整。

~ss($var); // outputs plain text
$output = @ss($var); // returns output instead of displaying it
! sage($var); // ignores depth limit for large objects
+ sage($var); // auto-expands the view
print sd($var); // saves output into "sage.html" in the current directory
print ! sd($var); // saves output into "sage.html" while also ignoring the output depth limit!

Sage 对调用代码进行标记化并内省以获取所有这些信息。所有可以使用前缀完成的事情也可以使用标准详细语法完成

~ss($var); 
// is equivalent to:
Sage::enabled(Sage::MODE_TEXT_ONLY);
Sage::dump($var);

如果你想要更多提示和技巧，请参阅下面的 高级部分

详细版本

如果你想将 Sage 作为永久代码的一部分使用（例如，测试辅助程序/记录器/异常报告程序等），你可以使用详细方式调用 Sage

// instead of sage()
Sage::dump('this looks way less hacky (yeah right:)');

// equivalent to sage(1);
Sage::trace(); 

// a real-life test helper:
class TestHelper{
  public function getVarDump(mixed $providedContext): string
  {
      if (! $providedContext) {
          return '';
      }
  
      $state = Sage::saveState();
      Sage::enabled(Sage::MODE_TEXT_ONLY);
      Sage::$aliases[]         = __CLASS__ . '::' . __FUNCTION__;
      Sage::$returnOutput      = true;
      Sage::$displayCalledFrom = false;
      $debugOutput             = Sage::dump($providedContext);
      
      Sage::saveState($state); // now reset settings to presumed defaults
  
      return PHP_EOL . $debugOutput;
  }
}

自定义

Sage 的主要目标是 无配置。也有几个高级使用选项的自定义选项。

在哪里存储配置？

  1. 将此条目添加到 composer.json 中的 autoload.files 配置
"autoload": {
    "files": [
        "config/sage.php" /* <--------------- create this file with your settings! */
    ]
}, ...
  1. 将设置放在 php.ini 中
; change sage theme:
sage.theme = solarized-dark
; always display all dump levels, almost always crashes the browser:
sage.maxLevels = 0
; set your IDE links
sage.editor = vscode
; disable Sage unless explicitly enabled
sage.enabled = 0
  1. 在任何地方™将所需设置包含在启动过程中。
require 'sage.phar';
Sage::$theme = Sage::THEME_LIGHT;

所有可用选项

Sage::$theme = Sage::THEME_ORIGINAL;

目前可用的主题有

  • Sage::THEME_ORIGINAL
  • Sage::THEME_LIGHT
  • Sage::THEME_SOLARIZED
  • Sage::THEME_SOLARIZED_DARK
Sage::$editor = ini_get('xdebug.file_link_format');

将可见源文件路径显示为可点击以打开您的编辑器。可用选项包括

'phpstorm-remote' - 默认（需要 IDE 远程控制插件），'sublime'，'textmate'，'emacs'，'macvim'，'phpstorm'，'idea'，'vscode'，'vscode-insiders'，'vscode-remote'，'vscode-insiders-remote'，'vscodium'，'atom'，'nova'，'netbeans'，'xdebug'

或者传递一个自定义字符串，其中 %file 应替换为完整文件路径，%line 应替换为行号以创建自定义链接。设置为 null 以禁用链接。

Sage::$displayCalledFrom = true;

是否显示 Sage 被调用的位置

Sage::$maxLevels = 7;

最大数组/对象嵌套层级，设置为 0/假以禁用

Sage::$expandedByDefault = false;

无需点击即可绘制已展开的丰富输出

Sage::$cliDetection = true;

在命令行模式下运行时启用检测并相应地调整输出格式。

Sage::$cliColors = true;

除上述设置外，当 Sage 在 UNIX 命令行中运行时也启用检测。尝试添加颜色，但如果以纯文本打开，颜色信息将显示为乱码。

Sage::$charEncodings =  [ 'UTF-8', 'Windows-1252', 'euc-jp' ]

可能的字符编码顺序。

Sage::$returnOutput = false;

Sage 返回输出而不是打印它。

Sage::$aliases;

添加新的自定义 Sage 包装器名称。可选，但对于回溯、变量名检测和修饰符的正常工作是必需的。接受数组或逗号分隔的字符串。使用 Class::method 表示方法。

🧙 高级技巧与窍门

本节正在建设中 :)

// we already saw:
sage($GLOBALS, $_SERVER); 
// you can also go shorter for the same result:
s($GLOBALS, $_SERVER);
// or you can go the verbose way, it's all equivalent:
Sage::dump($GLOBALS, $_SERVER); 


// ss() will display a more basic, javascript-free display (but with colors)
ss($GLOBALS, $_SERVER);
// to recap: s() or sage() - dumps. Add "d" to die afterwards: sd(), saged()
// preppend "s" to simplify output: ss(), ssage().
// works in combination, too: ssd() and ssagedd() will dump in "simple mode" and die!

// prepending a tilde will make the output *even more basic* (rich->basic and basic->plain text)
~d($GLOBALS, $_SERVER); // more on modifiers below

// show a trace
Sage::trace();
s(1); // shorthand works too!
s(2); // trace - but just the paths 
Sage::dump( debug_backtrace() ); // you can even pass a custom result from debug_trace and it will be recognized

// dump and die debugging
sd($GLOBALS, $_SERVER); // dd() might be taken by your framework
saged($GLOBALS, $_SERVER); // so this is an equivalent alternative
ssd($GLOBALS, $_SERVER); // available for plain display too!

// this will disable Sage completely
Sage::enabled(false);
sd('Get off my lawn!'); // no effect

  • Sage 支持键盘快捷键！在查看输出时按 d，其余的都是不言而喻的，试试吧！(提示：vim 风格的 hjkl 也一样有效)；

  • 调用 Sage::enabled(Sage::MODE_PLAIN); 切换到更简单、无 js 的输出。

  • 调用 Sage::enabled(Sage::MODE_TEXT_ONLY); 获取纯文本输出，您可以首先设置 Sage::$returnOutput = true; 然后保存或传递。

  • Sage 可以提供纯文本版本的输出，并且当通过在命令行模式下运行的 PHP 调用它时自动这样做。

  • 双击输出中的 [+] 符号将展开/折叠所有节点；三击一大块文本将选择所有文本。

  • 单击输出右侧的小箭头将在单独的窗口中打开它，您可以将其保留以进行比较。

  • Sage 支持主题

    有关自定义说明，请参阅下面的部分。

  • 如果变量是对象，则可以单击其类名以在您的 IDE 中打开该类。

  • 您可以使用几个实时前缀修饰符（可能的组合）

  • Sage 还包括一个您可能觉得有用的简单分析器。它是用来确定相对哪些代码块比其他代码块耗时更长的。

  • Sage 在 PHP 5.1 上运行得很好（找不到测试 5.0 的方法）。

Sage::dump( microtime() ); // just pass microtime() - also works if you pass NOTHING: s();
sleep( 1 );
Sage::dump( microtime(), 'after sleep(1)' );
sleep( 2 );
sd( microtime(), 'final call, after sleep(2)' );

常见问题解答

💬 它与 symfony/var-dumper 有何不同或更好？

  • 可见的 变量名
  • 键盘快捷键。按 d，其余的都是不言而喻的（使用箭头、空格、制表符、回车，你会明白的！）。
  • 调试回溯，具有对参数、被调用对象等的全面洞察。
  • 为许多已识别的类型提供自定义显示：自定义类型
  • 有纯文本、纯文本和丰富视图，有多个视觉主题 - 由专业设计师创建。
  • 大量易用性改进 - 如每个输出的页脚中的（可点击的）调用跟踪。
  • 支持便利修饰符，例如 @sage($var); 将返回而不是输出，-sage($var); 将 ob_clean 所有输出，使其成为页面上唯一的内容（有关更多信息，请参阅上述高级部分）。
  • 兼容性！完全在 PHP 5.1 - 8.1+ 上工作！
  • 代码简单得多 - 读取和贡献。
  • Sage 是 首先 出现的 - 从 2012 年之前 开始开发。它启发了现在无处不在的 dd 简写，开创了工具领域中的许多概念。

💬 其他还有哪些转储器

💬 为什么 Sage 看起来如此像 Kint？即：为什么这个存储库有如此少的星标？

因为它是 Kint，我是它的作者，然而项目却被一个恶意贡献者强行接管了！强行接管！

与其与风车战斗，我选择分叉并重命名最后一个好的版本，并以新名字继续！

您可以使用 Sage 作为 Kint 的直接替代品。很简单。

💬 当我们有 Xdebug 时，为什么使用 var_dump 风格的调试仍然相关？

  1. 实际上，Xdebug 安装和配置通常非常困难和耗时。
  2. 有很多用例中，使用 dump&die 更快。
  3. 您无法使用 XDebug 可视化更改数据的时间线。例如，在循环中输出的所有值。
  4. 还有更多微妙的使用场景，例如，如果你在某个地方跳过，就无法返回，但是使用 var-dumping 的值仍然存在...

顺便说一下，我几乎每天都使用 xdebug。与 Sage 一起使用。

已知问题

  1. 由于 PHP 8.2 中多行 Sage 调用的变量名检测已损坏。这只是 Backtrace 格式更改了报告的行，修复即将到来。

贡献

🎲 前提条件

  • 安装 Docker Compose。
  • 如果您使用的是 Windows 10+，则需要使用 WSL2。
    1. 设置：wsl --install
    2. 将 Ubuntu 设置为默认的 wsl shell：wsl --set-version Ubuntu 2。
    3. 以下所有命令必须在 wsl shell 中运行：wsl

做你的更改，但在提交之前运行

 docker compose run php composer build
 # OR (see Makefile):
 make build

来编译资源和构建 phar 文件。

作者

罗卡斯·舍利纽斯 (Raveren)

贡献者：https://github.com/php-sage/sage/graphs/contributors

许可证

在 MIT 许可证下授权

希望您使用 Sage 的感觉和我创造它的感觉一样！