{"id":18319424,"url":"https://github.com/kariricode-framework/kariricode-logging","last_synced_at":"2025-10-14T17:10:03.466Z","repository":{"id":257792065,"uuid":"768791092","full_name":"KaririCode-Framework/kariricode-logging","owner":"KaririCode-Framework","description":"A robust, flexible, and PSR-3 compliant logging component for the KaririCode Framework, providing comprehensive logging capabilities for PHP applications.","archived":false,"fork":false,"pushed_at":"2025-08-12T19:06:31.000Z","size":311,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-16T18:01:57.878Z","etag":null,"topics":["framework","framework-php","kariricode","logging","php"],"latest_commit_sha":null,"homepage":"https://kariricode.org","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KaririCode-Framework.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-03-07T18:31:16.000Z","updated_at":"2025-08-12T19:05:48.000Z","dependencies_parsed_at":"2024-09-23T19:02:17.511Z","dependency_job_id":"a1c2e70d-4954-4a96-9787-90cb2529a04d","html_url":"https://github.com/KaririCode-Framework/kariricode-logging","commit_stats":null,"previous_names":["kariricode-framework/kariricode-logging"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/KaririCode-Framework/kariricode-logging","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KaririCode-Framework%2Fkariricode-logging","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KaririCode-Framework%2Fkariricode-logging/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KaririCode-Framework%2Fkariricode-logging/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KaririCode-Framework%2Fkariricode-logging/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KaririCode-Framework","download_url":"https://codeload.github.com/KaririCode-Framework/kariricode-logging/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KaririCode-Framework%2Fkariricode-logging/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279020085,"owners_count":26086805,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["framework","framework-php","kariricode","logging","php"],"created_at":"2024-11-05T18:13:18.771Z","updated_at":"2025-10-14T17:10:03.448Z","avatar_url":"https://github.com/KaririCode-Framework.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# KaririCode Framework: Logging Component\n\n[![en](https://img.shields.io/badge/lang-en-red.svg)](README.md)\n[![pt-br](https://img.shields.io/badge/lang-pt--br-green.svg)](README.pt-br.md)\n\n![Docker](https://img.shields.io/badge/Docker-2496ED?style=for-the-badge\u0026logo=docker\u0026logoColor=white)\n![Makefile](https://img.shields.io/badge/Makefile-1D1D1D?style=for-the-badge\u0026logo=gnu\u0026logoColor=white)\n![PHP](https://img.shields.io/badge/PHP-777BB4?style=for-the-badge\u0026logo=php\u0026logoColor=white)\n![PHPUnit](https://img.shields.io/badge/PHPUnit-78E130?style=for-the-badge\u0026logo=phpunit\u0026logoColor=white)\n\nA robust, flexible, and PSR-3 compliant logging component for the KaririCode Framework, providing comprehensive logging capabilities for PHP applications.\n\n## Features\n\n- PSR-3 compliant\n- Supports multiple log channels (file, Slack, Papertrail, Elasticsearch)\n- Log encryption\n- Asynchronous logging support\n- Query and performance logging\n- Flexible logging formatters\n- Supports log rotation and cleanup\n- Circuit breaker and retry logic for logging\n- Detailed context and structured logging\n\n## Installation\n\nTo install the KaririCode Logging component, run the following command:\n\n```bash\ncomposer require kariricode/logging\n```\n\n## Basic Usage\n\n### Step 1: Environment Configuration\n\nThe **KaririCode Logging Component** relies on several environment variables to configure logging channels, log levels, external services, and other parameters. These variables are defined in a `.env` file, and the project comes with a default `.env.example` that should be copied to `.env` for initial setup.\n\nTo copy and create your `.env` file, run the following command:\n\n```bash\nmake setup-env\n```\n\nThis command will create a `.env` file if it doesn't already exist. Afterward, you can modify the values according to your requirements. Below are some key variables and their descriptions:\n\n```ini\n# Application environment (e.g., production, develop)\nKARIRICODE_APP=develop\n\n# PHP version and port used by the Docker service\nKARIRICODE_PHP_VERSION=8.3\nKARIRICODE_PHP_PORT=9303\n\n# Default log channel (e.g., file, stderr, slack)\nLOG_CHANNEL=file\n\n# Log level (e.g., debug, info, warning, error)\nLOG_LEVEL=debug\n\n# Encryption key for log data (ensure this is kept secure)\nLOG_ENCRYPTION_KEY=83302e6472acda6a8aeadf78409ceda3959994991393cdafbe23d2a46a148ba4\n\n# Slack configuration for sending critical logs\nSLACK_BOT_TOKEN=xoxb-your-bot-token-here\nSLACK_CHANNEL=#your-channel-name\n\n# Papertrail logging service configuration\nPAPERTRAIL_URL=logs.papertrailapp.com\nPAPERTRAIL_PORT=12345\n\n# Formatter for logs written to stderr\nLOG_STDERR_FORMATTER=json\n\n# Elasticsearch index for storing logs\nELASTIC_LOG_INDEX=logging-logs\n\n# Enable or disable asynchronous logging\nASYNC_LOG_ENABLED=true\n\n# Enable or disable query logging, and configure thresholds\nQUERY_LOG_ENABLED=true\nQUERY_LOG_CHANNEL=file\nQUERY_LOG_THRESHOLD=100\n\n# Enable or disable performance logging, and configure thresholds\nPERFORMANCE_LOG_ENABLED=true\nPERFORMANCE_LOG_CHANNEL=file\nPERFORMANCE_LOG_THRESHOLD=1000\n\n# Enable or disable error logging\nERROR_LOG_ENABLED=true\nERROR_LOG_CHANNEL=file\n\n# Log cleanup configuration (automatic removal of logs older than the specified number of days)\nLOG_CLEANER_ENABLED=true\nLOG_CLEANER_KEEP_DAYS=30\n\n# Circuit breaker configuration for managing log retries\nCIRCUIT_BREAKER_FAILURE_THRESHOLD=3\nCIRCUIT_BREAKER_RESET_TIMEOUT=60\n\n# Retry configuration for log failures\nRETRY_MAX_ATTEMPTS=3\nRETRY_DELAY=1000\nRETRY_MULTIPLIER=2\nRETRY_JITTER=100\n```\n\nEach of these variables can be adjusted according to your specific needs:\n\n- **Log Channels:** You can choose between different logging channels such as `file`, `slack`, or `stderr`. For example, `LOG_CHANNEL=slack` will send critical logs to a Slack channel.\n- **Log Levels:** This defines the minimum severity level for logs to be recorded (e.g., `debug`, `info`, `warning`, `error`, `critical`).\n- **External Services:** If you want to send logs to external services like Slack or Papertrail, ensure you correctly set `SLACK_BOT_TOKEN`, `PAPERTRAIL_URL`, and `PAPERTRAIL_PORT`.\n\n### Step 2: Loading Environment Variables and Configurations\n\nAfter configuring your `.env` file, you need to load the environment variables in your application and specify the path to the logging configuration file. This is done in the initialization of the application.\n\nHere’s how to set it up in your `application.php` file:\n\n```php\n\u003c?php\n\nrequire_once __DIR__ . '/../vendor/autoload.php';\n\nuse KaririCode\\Logging\\LoggerConfiguration;\nuse KaririCode\\Logging\\LoggerFactory;\nuse KaririCode\\Logging\\LoggerRegistry;\nuse KaririCode\\Logging\\Service\\LoggerServiceProvider;\nuse KaririCode\\Logging\\Util\\Config;\n\n// Load environment variables from the .env file\nConfig::loadEnv();\n\n// Specify the path to the logging configuration file\n$configPath = __DIR__ . '/../config/logging.php';\n\n// Initialize the logger configuration\n$loggerConfig = new LoggerConfiguration();\n$loggerConfig-\u003eload($configPath);\n\n// Create the logger factory and registry\n$loggerFactory = new LoggerFactory($loggerConfig);\n$loggerRegistry = new LoggerRegistry();\n\n// Register the loggers using the service provider\n$serviceProvider = new LoggerServiceProvider(\n    $loggerConfig,\n    $loggerFactory,\n    $loggerRegistry\n);\n$serviceProvider-\u003eregister();\n```\n\n### Step 3: Logging Example\n\nOnce the environment variables and the configuration are loaded, you can start using the loggers. Here's an example of logging messages at different levels:\n\n```php\n$defaultLogger = $loggerRegistry-\u003egetLogger('console');\n\n// Log messages with different severity levels\n$defaultLogger-\u003edebug('User email is john.doe@example.com');\n$defaultLogger-\u003einfo('User IP is 192.168.1.1');\n$defaultLogger-\u003enotice('User credit card number is 1234-5678-1234-5678', ['context' =\u003e 'credit card']);\n$defaultLogger-\u003ewarning('User phone number is (11) 91234-7890', ['context' =\u003e 'phone']);\n$defaultLogger-\u003eerror('An error occurred with email john.doe@example.com', ['context' =\u003e 'error']);\n$defaultLogger-\u003ecritical('Critical issue with IP 192.168.1.1', ['context' =\u003e 'critical']);\n$defaultLogger-\u003ealert('Alert regarding credit card 1234-5678-1234-5678', ['context' =\u003e 'alert']);\n$defaultLogger-\u003eemergency('Emergency with phone number 123-456-7890', ['context' =\u003e 'emergency']);\n```\n\n### Step 4: Using Specialized Loggers\n\nThe KaririCode Logging Component also supports specialized loggers, such as for asynchronous logging, query logging, and performance logging. Here’s how you can use these loggers:\n\n```php\n// Asynchronous logger\n$asyncLogger = $loggerRegistry-\u003egetLogger('async');\nif ($asyncLogger) {\n    for ($i = 0; $i \u003c 3; ++$i) {\n        $asyncLogger-\u003einfo(\"Async log message {$i}\", ['context' =\u003e \"batch {$i}\"]);\n    }\n}\n\n// Query logger for database queries\n$queryLogger = $loggerRegistry-\u003egetLogger('query');\n$queryLogger-\u003einfo('Executing query', ['query' =\u003e 'SELECT * FROM users', 'bindings' =\u003e []]);\n\n// Performance logger to track execution time\n$performanceLogger = $loggerRegistry-\u003egetLogger('performance');\n$performanceLogger-\u003edebug('Performance log', ['execution_time' =\u003e 1000]);\n\n// Error logger for handling critical errors\n$errorLogger = $loggerRegistry-\u003egetLogger('error');\n$errorLogger-\u003eerror('A critical error occurred', ['context' =\u003e 'Error details']);\n```\n\n### Step 5: Sending Critical Logs to Slack\n\nIf you've configured Slack as a logging channel in the `.env` file, you can send critical logs directly to a specified Slack channel:\n\n```php\n$slackLogger = $loggerRegistry-\u003egetLogger('slack');\n$slackLogger-\u003ecritical('This is a critical message sent to Slack', ['context' =\u003e 'slack']);\n```\n\nMake sure you’ve set your `SLACK_BOT_TOKEN` and `SLACK_CHANNEL` in the `.env` file for this to work properly.\n\n## Testing\n\nTo run tests for the KaririCode Logging Component, you can use PHPUnit. Run the following command inside your Docker container:\n\n```bash\nmake test\n```\n\nFor test coverage:\n\n```bash\nmake coverage\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support and Community\n\n- **Documentation**: [https://kariricode.org](https://kariricode.org)\n- **Issue Tracker**: [GitHub Issues](https://github.com/KaririCode-Framework/kariricode-contract/issues)\n- **Community**: [KaririCode Club Community](https://kariricode.club)\n- **Professional Support**: For enterprise-level support, contact us at support@kariricode.org\n\n## Acknowledgments\n\n- The KaririCode Framework team and contributors.\n- The PHP community for their continuous support and inspiration.\n\n---\n\nBuilt with ❤️ by the KaririCode team. Empowering developers to build more robust and flexible PHP applications.\n\nMaintained by Walmir Silva - [walmir.silva@kariricode.org](mailto:walmir.silva@kariricode.org)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkariricode-framework%2Fkariricode-logging","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkariricode-framework%2Fkariricode-logging","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkariricode-framework%2Fkariricode-logging/lists"}