Add logging support.

Log user input, command invocations, and executed code to a PSR-3 logger
or a simple callback.

Configuration:

    // Simple callback
    $config->setLogging(function ($kind, $data) {
        file_put_contents('/tmp/psysh.log', "[$kind] $data\n", FILE_APPEND);
    });

    // PSR-3 logger with defaults
    // (input=info, command=info, execute=debug)
    $config->setLogging($psrLogger);

    // Granular control per event type
    $config->setLogging([
        'logger' => $psrLogger,
        'level' => [
            'input'   => 'info',
            'command' => false, // disable
            'execute' => 'debug',
        ],
    ]);

Fixes #821, #651, #565

Author: bobthecow

phpstan.neon.dist

@@ -16,6 +16,8 @@ parameters:
     # See: https://github.com/bobthecow/psysh/pull/738#issuecomment-1202622730
     - src/Readline/Hoa/FileLink.php
     - src/Util/Str.php
+    # Fake PSR-3 logger implements interface that may not exist when psr/log isn't installed
+    - test/Util/FakePsrLogger.php
   bootstrapFiles:
     - vendor-bin/phpstan/bootstrap.php
   reportUnmatchedIgnoredErrors: true

src/Configuration.php

@@ -13,8 +13,11 @@
 
 use Psy\Exception\DeprecatedException;
 use Psy\Exception\RuntimeException;
+use Psy\ExecutionLoop\ExecutionLoggingListener;
+use Psy\ExecutionLoop\InputLoggingListener;
 use Psy\ExecutionLoop\ProcessForker;
 use Psy\Formatter\SignatureFormatter;
+use Psy\Logger\CallbackLogger;
 use Psy\Manual\ManualInterface;
 use Psy\Manual\V2Manual;
 use Psy\Manual\V3Manual;
@@ -65,6 +68,7 @@ class Configuration
         'historySize',
         'implicitUse',
         'interactiveMode',
+        'logging',
         'manualDbFile',
         'pager',
         'prompt',
@@ -113,6 +117,7 @@ class Configuration
     private array $newMatchers = [];
     private ?array $autoloadWarmers = null;
     private $implicitUse = false;
+    private ?ShellLogger $logger = null;
     private int $errorLoggingLevel = \E_ALL;
     private bool $warnOnMultipleConfigs = false;
     private string $colorMode = self::COLOR_MODE_AUTO;
@@ -1527,6 +1532,164 @@ public function getImplicitUse()
         return $this->implicitUse;
     }
 
+    /**
+     * Configure logging.
+     *
+     * Logs PsySH input, commands, and executed code to the provided logger.
+     * Accepts a PSR-3 logger, a simple callback, or an array for more control
+     * over log levels.
+     *
+     * Examples:
+     *
+     *     // Simple callback logging
+     *     $config->setLogging(function ($kind, $data) {
+     *         $line = sprintf("[%s] %s\n", $kind, $data);
+     *         file_put_contents('/tmp/psysh.log', $line, FILE_APPEND);
+     *     });
+     *
+     *     // PSR-3 logger with defaults (input=info, command=info, execute=debug)
+     *     $config->setLogging($psrLogger);
+     *
+     *     // Set single level for all event types
+     *     $config->setLogging([
+     *         'logger' => $psrLogger,
+     *         'level' => 'debug',
+     *     ]);
+     *
+     *     // Granular control over each event type
+     *     $config->setLogging([
+     *         'logger' => $psrLogger,
+     *         'level' => [
+     *             'input'   => 'info',
+     *             'command' => false, // disable logging
+     *             'execute' => 'debug',
+     *         ],
+     *     ]);
+     *
+     * @param \Psr\Log\LoggerInterface|callable|array $logging
+     */
+    public function setLogging($logging): void
+    {
+        $this->logger = $this->parseLoggingConfig($logging);
+    }
+
+    /**
+     * Get a ShellLogger instance if logging is configured.
+     *
+     * @return ShellLogger|null
+     */
+    public function getLogger(): ?ShellLogger
+    {
+        return $this->logger;
+    }
+
+    /**
+     * Get an InputLoggingListener if input logging is enabled.
+     *
+     * @return InputLoggingListener|null
+     */
+    public function getInputLogger(): ?InputLoggingListener
+    {
+        $logger = $this->getLogger();
+        if ($logger === null || $logger->isInputDisabled()) {
+            return null;
+        }
+
+        return new InputLoggingListener($logger);
+    }
+
+    /**
+     * Get an ExecutionLoggingListener if execution logging is enabled.
+     *
+     * @return ExecutionLoggingListener|null
+     */
+    public function getExecutionLogger(): ?ExecutionLoggingListener
+    {
+        $logger = $this->getLogger();
+        if ($logger === null || $logger->isExecuteDisabled()) {
+            return null;
+        }
+
+        return new ExecutionLoggingListener($logger);
+    }
+
+    /**
+     * Parse logging configuration.
+     *
+     * @param \Psr\Log\LoggerInterface|Logger\CallbackLogger|callable|array $config
+     *
+     * @return ShellLogger
+     */
+    private function parseLoggingConfig($config): ShellLogger
+    {
+        if (!\is_array($config)) {
+            $config = ['logger' => $config];
+        }
+
+        if (!isset($config['logger'])) {
+            throw new \InvalidArgumentException('Logging config array must include a "logger" key');
+        }
+
+        $logger = $config['logger'];
+
+        if (\is_callable($logger)) {
+            $logger = new CallbackLogger($logger);
+        }
+
+        if (!$this->isLogger($logger)) {
+            throw new \InvalidArgumentException('Logging "logger" must be a logger instance or callable');
+        }
+
+        $defaults = [
+            'input'   => 'info',
+            'command' => 'info',
+            'execute' => 'debug',
+        ];
+
+        if (isset($config['level'])) {
+            $level = $config['level'];
+
+            // String: apply same level to all types
+            if (\is_string($level)) {
+                $levels = [
+                    'input'   => $level,
+                    'command' => $level,
+                    'execute' => $level,
+                ];
+            } elseif (\is_array($level)) {
+                // Array: granular per-type levels
+                $levels = [
+                    'input'   => $level['input'] ?? $defaults['input'],
+                    'command' => $level['command'] ?? $defaults['command'],
+                    'execute' => $level['execute'] ?? $defaults['execute'],
+                ];
+            } else {
+                throw new \InvalidArgumentException('Logging "level" must be a string or array');
+            }
+        } else {
+            $levels = $defaults;
+        }
+
+        return new ShellLogger($logger, $levels);
+    }
+
+    /**
+     * Check if a value is a valid logger instance.
+     *
+     * @param mixed $logger
+     *
+     * @return bool
+     */
+    private function isLogger($logger): bool
+    {
+        if ($logger instanceof CallbackLogger) {
+            return true;
+        }
+
+        // Safe check for LoggerInterface without requiring psr/log as a dependency
+        return \interface_exists('Psr\Log\LoggerInterface') && $logger instanceof \Psr\Log\LoggerInterface;
+    }
+
     /**
      * @deprecated Use `addMatchers` instead
      *

src/ExecutionLoop/ExecutionLoggingListener.php

@@ -0,0 +1,51 @@
+<?php
+
+/*
+ * This file is part of Psy Shell.
+ *
+ * (c) 2012-2025 Justin Hileman
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Psy\ExecutionLoop;
+
+use Psy\Shell;
+use Psy\ShellLogger;
+
+/**
+ * Execution logging listener.
+ *
+ * Logs code about to be executed to a ShellLogger.
+ */
+class ExecutionLoggingListener extends AbstractListener
+{
+    private ShellLogger $logger;
+
+    /**
+     * @param ShellLogger $logger
+     */
+    public function __construct(ShellLogger $logger)
+    {
+        $this->logger = $logger;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public static function isSupported(): bool
+    {
+        return true;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function onExecute(Shell $shell, string $code)
+    {
+        $this->logger->logExecute($code);
+
+        return null;
+    }
+}

src/ExecutionLoop/InputLoggingListener.php

@@ -0,0 +1,51 @@
+<?php
+
+/*
+ * This file is part of Psy Shell.
+ *
+ * (c) 2012-2025 Justin Hileman
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Psy\ExecutionLoop;
+
+use Psy\Shell;
+use Psy\ShellLogger;
+
+/**
+ * Input logging listener.
+ *
+ * Logs user code input to a ShellLogger.
+ */
+class InputLoggingListener extends AbstractListener
+{
+    private ShellLogger $logger;
+
+    /**
+     * @param ShellLogger $logger
+     */
+    public function __construct(ShellLogger $logger)
+    {
+        $this->logger = $logger;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public static function isSupported(): bool
+    {
+        return true;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function onInput(Shell $shell, string $input)
+    {
+        $this->logger->logInput($input);
+
+        return null;
+    }
+}

src/Logger/CallbackLogger.php

@@ -0,0 +1,61 @@
+<?php
+
+/*
+ * This file is part of Psy Shell.
+ *
+ * (c) 2012-2025 Justin Hileman
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Psy\Logger;
+
+/**
+ * Callback logger.
+ *
+ * A simple logger that calls a callback with the log kind and data.
+ */
+class CallbackLogger
+{
+    private $callback;
+
+    /**
+     * @param callable $callback Callback to invoke with (string $kind, string $data)
+     */
+    public function __construct(callable $callback)
+    {
+        $this->callback = $callback;
+    }
+
+    /**
+     * Log a message.
+     *
+     * @param string $level   Log level
+     * @param string $message Log message
+     * @param array  $context Context data
+     */
+    public function log(string $level, string $message, array $context = []): void
+    {
+        // Determine the kind from the message
+        switch ($message) {
+            case 'PsySH input':
+                $kind = 'input';
+                break;
+            case 'PsySH command':
+                $kind = 'command';
+                break;
+            case 'PsySH execute':
+                $kind = 'execute';
+                break;
+            default:
+                $kind = 'unknown';
+                break;
+        }
+
+        // Extract the data from context
+        $data = $context[$kind] ?? $context['code'] ?? '';
+
+        \call_user_func($this->callback, $kind, $data);
+    }
+}