PHPackages                             dxgx/tree-size-mailer - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. dxgx/tree-size-mailer

ActiveLibrary[Utility & Helpers](/categories/utility)

dxgx/tree-size-mailer
=====================

Laravel package for generating and emailing directory tree size reports

v1.7.0(2w ago)042MITPHPPHP ^8.2

Since May 14Pushed 1w agoCompare

[ Source](https://github.com/dxgx/tree-size-mailer)[ Packagist](https://packagist.org/packages/dxgx/tree-size-mailer)[ RSS](/packages/dxgx-tree-size-mailer/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (4)Versions (11)Used By (0)

Tree Size Mailer
================

[](#tree-size-mailer)

A Laravel package that generates comprehensive directory tree size reports and emails them to specified recipients. Perfect for monitoring disk usage, identifying large directories, and tracking storage growth over time.

Features
--------

[](#features)

- 🌳 **Tree View** - Hierarchical directory structure with clean indentation (shown first)
- 📊 **Overview Section** - High-level directory size summary
- 📂 **Detailed Report** - All directories with configurable row limits
- 📦 **Custom Breakdowns** - Break down specific directories with custom depth levels
- 🔍 **Section Filters** - Each section shows applied filters (size limits, exclusions)
- ⚙️ **Fully Configurable** - Control scan depth, size thresholds, and recipients
- 📧 **Email Reports** - Automatic email delivery with HTML formatting
- 🔧 **Environment Support** - Configure via `.env` variables

Requirements
------------

[](#requirements)

- PHP 8.2 or higher
- Laravel 11.x or 12.x
- Configured mail driver

Installation
------------

[](#installation)

Install the package via Composer:

```
composer require dxgx/tree-size-mailer
```

### Publish Configuration

[](#publish-configuration)

Publish the configuration file to customize settings:

```
php artisan vendor:publish --tag=tree-size-mailer-config
```

This creates `config/tree-size-mailer.php` in your application.

### Publish Views (Optional)

[](#publish-views-optional)

If you want to customize the email template:

```
php artisan vendor:publish --tag=tree-size-mailer-views
```

This publishes the email blade template to `resources/views/vendor/tree-size-mailer/`.

Configuration
-------------

[](#configuration)

### Configuration File

[](#configuration-file)

After publishing, edit `config/tree-size-mailer.php`:

```
return [
    // Email recipients (array of email addresses)
    'recipients' => [
        env('TREE_SIZE_REPORT_EMAIL', 'admin@example.com'),
    ],

    // Base directory to scan (defaults to Laravel base path)
    'scan_path' => env('TREE_SIZE_REPORT_SCAN_PATH', base_path()),

    // Maximum directory depth for overview and tree view
    'max_depth' => (int) env('TREE_SIZE_REPORT_MAX_DEPTH', 5),

    // Minimum size (bytes) for detailed report entries
    'min_file_size' => (int) env('TREE_SIZE_REPORT_MIN_SIZE', 102400), // 100 KB

    // Minimum size (bytes) for overview section
    'min_overview_size' => (int) env('TREE_SIZE_REPORT_MIN_OVERVIEW_SIZE', 1048576), // 1 MB

    // Minimum size (bytes) for tree view
    'min_tree_size' => (int) env('TREE_SIZE_REPORT_MIN_TREE_SIZE', 1048576), // 1 MB

    // Excluded directory patterns (supports wildcards)
    'excluded_dirs' => [
        // '/node_modules',
        // '/vendor*',
        // '*/cache',
        // '*test*',
    ],

    // Custom directory breakdowns with specific depth levels
    'breakdown_dirs' => [
        // '/vendor' => 3,
        // '/storage/app/public/photos' => 2,
    ],

    // Maximum rows in detailed report section (0 = unlimited)
    'detailed_max_rows' => (int) env('TREE_SIZE_REPORT_DETAILED_MAX_ROWS', 100),

    // Application name for email subject
    'app_name' => env('APP_NAME', 'Laravel App'),

    // Email layout sections (customize which sections to include)
    'layout' => [
        'root_level_overview',
        'directory_tree',
        'detailed_directory_sizes',
        'custom_breakdowns',
    ],
];
```

### Report Layout Configuration

[](#report-layout-configuration)

Control which sections appear in your email reports and their order. The `layout` array accepts 1-3 sections from the available options:

**Available Sections:**

- `root_level_overview` - First-level directories with total sizes
- `directory_tree` - Hierarchical tree structure with indentation
- `detailed_directory_sizes` - Flat list sorted by size (all directory levels)
- `custom_breakdowns` - Custom sections for directories defined in `breakdown_dirs`

**Configuration Examples:**

```
// Show only overview and tree (minimal report)
'layout' => [
    'root_level_overview',
    'directory_tree',
],

// Show detailed report only
'layout' => [
    'detailed_directory_sizes',
],

// Custom order (tree view first, then detailed)
'layout' => [
    'directory_tree',
    'detailed_directory_sizes',
    'custom_breakdowns',
],

// All sections (default)
'layout' => [
    'root_level_overview',
    'directory_tree',
    'detailed_directory_sizes',
    'custom_breakdowns',
],
```

**Email Format:** The package automatically generates both HTML (styled tables) and plain text (ASCII formatted) versions of the email for maximum compatibility.

### Excluding Directories

[](#excluding-directories)

You can exclude specific directories from all report sections using wildcard patterns. Only directory paths are checked (not individual files).

**Pattern Syntax:**

- `/vendor*` - Excludes all directories starting with `/vendor`
    *(Matches: `/vendor`, `/vendor_folder`, `/vendor/links/photos/logs`)*
- `*vendor` - Excludes all directories ending with `vendor`
    *(Matches: `/vendor`, `/super_duper_vendor`, but not `/my_vendor_is`)*
- `*vendor*` - Excludes all directories containing `vendor` anywhere
    *(Matches: `/vendor`, `/vendor_path`, `/my/vendor/path`, `/my/path/vendor`)*

**Configuration Example:**

```
'excluded_dirs' => [
    '/node_modules',        // Exclude node_modules directory
    '/vendor*',             // Exclude vendor and any vendor_* directories
    '*/cache',              // Exclude any cache directory at any level
    '*/storage/logs',       // Exclude storage/logs directories
    '*test*',               // Exclude any directory with 'test' in the name
    '*/dist',               // Exclude build output directories
    Custom Breakdowns**: Excluded patterns still apply within breakdowns
- **Tree View**: Excluded directory branches are completely omitted

### Custom Directory Breakdowns

Create dedicated sections for specific directories with custom depth levels. Directories in `breakdown_dirs` will:
- Have their own section in the email report
- Be excluded from the "Detailed Directory Sizes" section (to avoid duplication)
- Still appear in the tree view
- Have their sizes calculated and included in totals

**Configuration Example:**

```php
'breakdown_dirs' => [
    '/vendor' => 3,                          // Composer packages (3 levels)
    '/storage/app/public/photos' => 2,       // Photo storage (2 levels)
    '/node_modules' => 2,                    // NPM packages (2 levels)
    '/public_html' => 2,                     // Public assets (2 levels)
],
```

Each breakdown will create a section like "Vendor Breakdown (3 Levels)" showing directories up to the specified depth.

### Detailed Report Row Limit

[](#detailed-report-row-limit)

TREE\_SIZE\_REPORT\_DETAILED\_MAX\_ROWS=100 # Limit detailed section Control the maximum number of rows shown in the "Detailed Directory Sizes" section:

```
'detailed_max_rows' => 100,  // Limit to 100 rows (default)
'detailed_max_rows' => 0,    // Show all rows (unlimited)
```

This helps keep email reports manageable when scanning large directory structures.

```

**Performance Note:** Exclusion patterns are checked in order. List more specific patterns first for optimal performance.

**Effect on Reports:**
- **Detailed Report**: Excluded directories won't appear
- **Overview Section**: Files in excluded directories are not counted
- **Vendor Breakdown**: Vendor packages matching exclusion patterns won't appear
- **Tree View**: Excluded directory branches are completely omitted

### Environment Variables

Add these to your `.env` file:

```bash
# Required: Email recipient(s)
TREE_SIZE_REPORT_EMAIL=admin@example.com

# Optional: Advanced configuration
TREE_SIZE_REPORT_SCAN_PATH=/path/to/scan
TREE_SIZE_REPORT_MAX_DEPTH=5
TREE_SIZE_REPORT_MIN_SIZE=102400         # 100 KB
TREE_SIZE_REPORT_MIN_OVERVIEW_SIZE=1048576  # 1 MB
TREE_SIZE_REPORT_MIN_TREE_SIZE=1048576      # 1 MB

```

### Multiple Recipients

[](#multiple-recipients)

To send reports to multiple email addresses, edit the config file directly:

```
'recipients' => [
    'admin@example.com',
    'devops@example.com',
    'manager@example.com',
],
```

Usage
-----

[](#usage)

### Manual Execution

[](#manual-execution)

Run the report command manually:

```
php artisan dg:tree-size-mailer
```

The command will:

1. Scan the configured directory
2. Generate size reports (overview, detailed, vendor breakdown, tree view)
3. Email the report to all configured recipients
4. Display summary statistics in the console

### Scheduled Execution

[](#scheduled-execution)

Add the command to your application's scheduler for automatic reports.

#### Laravel 11+ (using `schedule` in `bootstrap/app.php` or `routes/console.php`)

[](#laravel-11-using-schedule-in-bootstrapappphp-or-routesconsolephp)

**Option 1: In `routes/console.php`:**

```
use Illuminate\Support\Facades\Schedule;

Schedule::command('dg:tree-size-mailer')->daily();
```

**Option 2: In `bootstrap/app.php`:**

```
->withSchedule(function (Schedule $schedule) {
    $schedule->command('dg:tree-size-mailer')->daily();
})
```

#### Laravel 10 and below (using `app/Console/Kernel.php`)

[](#laravel-10-and-below-using-appconsolekernelphp)

```
protected function schedule(Schedule $schedule)
{
    $schedule->command('dg:tree-size-mailer')->daily();
}
```

### Scheduling Examples

[](#scheduling-examples)

```
// Daily at 2:00 AM
Schedule::command('dg:tree-size-mailer')->dailyAt('02:00');

// Weekly on Monday at 6:00 AM
Schedule::command('dg:tree-size-mailer')->weeklyOn(1, '06:00');

// Monthly on the 1st at 3:00 AM
Schedule::command('dg:tree-size-mailer')->monthlyOn(1, '03:00');

// Every Sunday at midnight
Schedule::command('dg:tree-size-mailer')->weekly()->sundays()->at('00:00');
```

Report Sections
---------------

[](#report-sections)

the following sections (in order):

### 1. Directory Tree

[](#1-directory-tree)

Hierarchical tree view with clean 4-space indentation showing the directory structure. Only includes directories larger than `min_tree_size` (default: 1 MB). Shows applied depth and size filters at the bottom.

**Display format:** Uses fixed-width font with simple indentation (no tree characters).

### 2. Overview

[](#2-overview)

High-level summary of directories up to the configured depth (default: 5 levels). Shows only directories larger than `min_overview_size` (default: 1 MB). Excludes directories configured in `breakdown_dirs`.

**Filter note:** Shows max depth, min size, and excluded breakdown directories.

### 3. Detailed Directory Sizes

[](#3-detailed-directory-sizes)

Complete list of all directories with their sizes, sorted by size descending. Limited to `detailed_max_rows` (default: 100). Excludes:

- Directories smaller than `min_file_size` (default: 100 KB)
- Directories matching configured exclusion patterns
- Directories in `breakdown_dirs` (shown in their own sections)

**Filter note:** Shows row limit, min size, and excluded directories.

### 4. Custom Direc

[](#4-custom-direc)

Detailed: 100 dirs, 3.12 GB Vendor Breakdown (3 Levels): 103 items, 123.99 MB Public Html Breakdown (2 Levels): 6 items, 5.77 MB Tree: 89 items, 2.67 GB Tree size report emailed to:

```

Note: Overview section no longer shows total size to avoid confusion with breakdown totals.
## Console Output

When you run the command, you'll see summary statistics:

```

Tree size report generated: Overview: 45 dirs, 2.34 GB Detailed: 312 dirs, 3.12 GB Vendor: 156 packages, 487.23 MB Tree: 89 items, 2.67 GB Tree size report emailed to:

```

## Customization

### Custom Email Template

After publishing views, customize `resources/views/vendor/tree-size-mailer/email.blade.php`. The template receives these variables:

- `$rows` - Detailed directory list
- `$overview` - Overview section data
- `$vendorBreakdown` - Vendor package sizes
- `$treeView` - Hierarchical tree data
- `$basePath` - Scanned directory path
- `$generatedAt` - Report generation timestamp

### Custom Scan Path

To scan a different directory (e.g., multi-tenant setup):

```php
'scan_path' => '/var/www/client-sites/client-123',

```

Or use environment variable:

```
TREE_SIZE_REPORT_SCAN_PATH=/var/www/client-sites/client-123
```

Size Thresholds
---------------

[](#size-thresholds)

Adjust thresholds to control report granularity:

- **Small projects:** Lower thresholds (50 KB, 500 KB)
- **Large projects:** Higher thresholds (1 MB, 10 MB)
- **Storage monitoring:** Lower overview threshold, higher detailed threshold

Example for large project:

```
'min_file_size' => 524288,        // 512 KB
'min_overview_size' => 10485760,  // 10 MB
'min_tree_size' => 5242880,       // 5 MB
```

Troubleshooting
---------------

[](#troubleshooting)

### No Email Received

[](#no-email-received)

1. Verify mail configuration: `php artisan config:cache`
2. Check mail logs: `tail -f storage/logs/laravel.log`
3. Test mail: `php artisan tinker` then `Mail::raw('Test', fn($msg) => $msg->to('test@example.com')->subject('Test'))`

### Permission Errors

[](#permission-errors)

Ensure the web server user has read access to the scan directory:

```
chmod -R 755 /path/to/scan
```

### Memory Errors

[](#memory-errors)

For very large directory trees, increase PHP memory:

```
php -d memory_limit=512M artisan dg:tree-size-mailer
```

### Timeout Issues

[](#timeout-issues)

For slow file systems, increase max execution time:

```
php -d max_execution_time=600 artisan dg:tree-size-mailer
```

Security Considerations
-----------------------

[](#security-considerations)

- Limit scan paths to trusted directories
- Restrict email recipients to authorized personnel
- Be cautious when publishing views (may expose directory structure)
- Use queue for large scans to avoid blocking requests

License
-------

[](#license)

MIT License. See LICENSE file for details.

Support
-------

[](#support)

For issues, questions, or contributions, please contact:

- Email:

Changelog
---------

[](#changelog)

See [CHANGELOG.md](CHANGELOG.md) for version history.

###  Health Score

44

—

FairBetter than 90% of packages

Maintenance97

Actively maintained with recent releases

Popularity11

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity52

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

10

Last Release

20d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/f2a12a26ca730b7645484bc8744660dcde380c213b39e6b626e1be872444f4ae?d=identicon)[dxgx](/maintainers/dxgx)

---

Top Contributors

[![dxgx](https://avatars.githubusercontent.com/u/3294038?v=4)](https://github.com/dxgx "dxgx (14 commits)")

---

Tags

laraveldisk usagedirectory-sizeemail-reporttree-size

###  Code Quality

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/dxgx-tree-size-mailer/health.svg)

```
[![Health](https://phpackages.com/badges/dxgx-tree-size-mailer/health.svg)](https://phpackages.com/packages/dxgx-tree-size-mailer)
```

###  Alternatives

[laravel/ai

The official AI SDK for Laravel.

9782.1M153](/packages/laravel-ai)[livewire/flux

The official UI component library for Livewire.

9466.8M119](/packages/livewire-flux)[flarum/core

Delightfully simple forum software.

261.4M2.2k](/packages/flarum-core)[zidbih/laravel-deadlock

Make temporary Laravel workarounds expire and fail CI when ignored.

954.0k](/packages/zidbih-laravel-deadlock)[interaction-design-foundation/laravel-geoip

Support for multiple Geographical Location services.

19253.0k3](/packages/interaction-design-foundation-laravel-geoip)[tomshaw/electricgrid

A feature-rich Livewire package designed for projects that require dynamic, interactive data tables.

119.2k](/packages/tomshaw-electricgrid)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)