This document provides detailed instructions for upgrading between major versions of Contributte Datagrid.
- Upgrading from 7.0.x to 7.1.x
- Upgrading from 6.x to 7.0.x
- Upgrading from 5.x to 6.0.x
- Upgrading from 4.x to 5.0.x
Version 7.1.x introduces a pluggable state storage system and removes several backward compatibility features that were deprecated in 7.0.x.
Impact: High - affects applications using custom translations
Before (v7.0.x):
// These were automatically converted to contributte_* keys
new SimpleTranslator([
'ublaboo_datagrid.no_items' => 'No records found',
'ublaboo_datagrid.choose' => 'Choose...',
'ublaboo_datagrid.reset_filter' => 'Reset filter'
]);After (v7.1.x):
// Must use contributte_* keys directly
new SimpleTranslator([
'contributte_datagrid.no_items' => 'No records found',
'contributte_datagrid.choose' => 'Choose...',
'contributte_datagrid.reset_filter' => 'Reset filter'
]);Migration Steps:
- Update all
ublaboo_datagrid.*translation keys tocontributte_datagrid.* - Search your codebase for
ublaboo_datagridand replace withcontributte_datagrid
Impact: Medium - affects applications using HappyInputs
Before (v7.0.x):
$grid->useHappyComponents(true);
$shouldUse = $grid->shouldUseHappyComponents();After (v7.1.x):
// These methods no longer exist
// Form inputs now use standard Bootstrap 5 classes automaticallyMigration Steps:
- Remove all calls to
useHappyComponents()andshouldUseHappyComponents() - Update your CSS if you were relying on HappyInputs-specific styling
- Form inputs will automatically use Bootstrap 5 classes
Impact: High - affects applications using custom state management
Before (v7.0.x):
$grid->setStrictSessionFilterValues(true);
$data = $grid->getSessionData($key);
$grid->saveSessionData($key, $value);
$grid->deleteSessionData($key);After (v7.1.x):
$grid->setStrictStorageFilterValues(true);
$data = $grid->getStorageData($key, $defaultValue);
$grid->saveStorageData($key, $value);
$grid->deleteStorageData($key);Migration Steps:
- Replace
setStrictSessionFilterValueswithsetStrictStorageFilterValues - Replace
getSessionDatawithgetStorageData(note: new optional default value parameter) - Replace
saveSessionDatawithsaveStorageData - Replace
deleteSessionDatawithdeleteStorageData
Impact: Low to Medium - affects applications using deprecated assets
Before (v7.0.x):
import 'datagrid-all';
import 'datagrid-all.min';After (v7.1.x):
import 'datagrid-full';
import 'datagrid-full.min';Migration Steps:
- Update asset imports from
datagrid-all.*todatagrid-full.* - Update any build scripts that reference the old asset names
Impact: Low - affects applications using ublaboo/* namespaces
Before (v7.0.x):
// compatibility.php provided these aliases
use Ublaboo\DataGrid\DataGrid;
use Ublaboo\DataGrid\Column\ColumnText;After (v7.1.x):
// Must use Contributte namespaces directly
use Contributte\Datagrid\DataGrid;
use Contributte\Datagrid\Column\ColumnText;Benefit: Allows custom storage backends for grid state
use Contributte\Datagrid\Storage\IStateStorage;
use Contributte\Datagrid\Storage\SessionStateStorage;
use Contributte\Datagrid\Storage\NoopStateStorage;
// Default: Session-based storage (same as before)
$grid->setStateStorage(new SessionStateStorage());
// Alternative: No persistence
$grid->setStateStorage(new NoopStateStorage());
// Custom implementation
class RedisStateStorage implements IStateStorage {
public function saveState(string $key, mixed $value): void {
// Your Redis implementation
}
public function loadState(string $key, mixed $defaultValue = null): mixed {
// Your Redis implementation
}
public function deleteState(string $key): void {
// Your Redis implementation
}
}
$grid->setStateStorage(new RedisStateStorage());// Disable Doctrine Paginator for performance optimization
$grid->getDataSource()->setUsePaginator(false);setStrictSessionFilterValues()→ UsesetStrictStorageFilterValues()
Version 7.0.x is a major modernization release that requires PHP 8.2+ and removes legacy compatibility layers.
Before (v6.x): PHP 7.2+ After (v7.0.x): PHP 8.2+
Migration Steps:
- Upgrade your PHP version to 8.2 or higher
- Update your server/container configurations
- Test all functionality with PHP 8.2+
Update your composer.json:
{
"require": {
"php": "^8.2",
"contributte/datagrid": "^7.0"
}
}All backward compatibility layers for the Ublaboo → Contributte transition have been removed.
Migration Steps:
- Ensure all code uses
Contributte\Datagridnamespace (should be done in 6.x upgrade) - Remove any references to
ublaboo/datagridpackage - Update translation keys to use
contributte_datagrid.*prefix
The codebase now utilizes PHP 8.2+ language features.
Potential Impact:
- Union types and intersection types usage
- Enum usage where applicable
- Improved type declarations
- Performance optimizations
-
Before upgrading to 7.0.x, ensure your 6.x installation is up to date:
composer require contributte/datagrid:^6.10
-
Test thoroughly with the latest 6.x version
-
Update PHP and dependencies:
# Update PHP to 8.2+ composer require php:^8.2 # Update to 7.0.x composer require contributte/datagrid:^7.0
Version 6.0.x represents a major modernization with namespace changes, PHP 7.2+ requirement, and Nette 3.0 support.
Before (v5.x): PHP 5.6+ After (v6.0.x): PHP 7.2+
Before (v5.x): Nette 2.4+ After (v6.0.x): Nette 3.0+
Impact: Critical - affects all imports
Before (v5.x):
use Ublaboo\DataGrid\DataGrid;
use Ublaboo\DataGrid\Column\ColumnText;
use Ublaboo\DataGrid\Column\Action\Confirmation\StringConfirmation;
use Ublaboo\DataGrid\DataSource\DibiFluentDataSource;After (v6.0.x):
use Contributte\Datagrid\DataGrid;
use Contributte\Datagrid\Column\ColumnText;
use Contributte\Datagrid\Column\Action\Confirmation\StringConfirmation;
use Contributte\Datagrid\DataSource\DibiFluentDataSource;Migration Steps:
-
Update Composer dependency:
{ "require": { "contributte/datagrid": "^6.0" } }Remove
ublaboo/datagridfrom dependencies. -
Update all namespace imports:
- Search and replace
Ublaboo\\DataGridwithContributte\\Datagrid - Update all
usestatements throughout your codebase
- Search and replace
-
Update service configurations:
# Before (Neon) services: - Ublaboo\DataGrid\DataGrid # After (Neon) services: - Contributte\Datagrid\DataGrid
Impact: Medium - affects frontend builds
Before (v5.x):
<!-- Bootstrap 3 support -->
<link rel="stylesheet" href="datagrid.css">
<script src="datagrid.js"></script>After (v6.0.x):
<!-- Bootstrap 4+ required -->
<link rel="stylesheet" href="datagrid.css">
<script src="datagrid.js"></script>Migration Steps:
-
Update to Bootstrap 4+:
- Remove Bootstrap 3 stylesheets
- Install Bootstrap 4 or 5
- Update your application's Bootstrap classes
-
Review custom CSS:
- Check for conflicts with new CSS class names
- Update any custom datagrid styling
- Test responsive behavior
Impact: Medium - affects custom templates
Migration Steps:
- Review any custom datagrid templates
- Update template syntax for Latte 2.8+
- Test all template rendering
Impact: Low to Medium - affects advanced usage
Some method signatures have been updated for better type safety:
Migration Steps:
- Review any classes extending datagrid components
- Update method signatures to match new type declarations
- Test all custom extensions
- Webpack-based build system
- Improved CSS and JavaScript structure
- Better browser compatibility
- Full PHP 7.2+ type declarations
- Improved IDE support and IntelliSense
- Better error reporting
- Optimized for large datasets
- Reduced memory usage
- Faster rendering
- Update PHP to 7.2+
- Update Nette Framework to 3.0+
- Update Bootstrap to 4+
- Change composer dependency from
ublaboo/datagridtocontributte/datagrid - Update all namespace imports from
Ublaboo\\DataGridtoContributte\\Datagrid - Update service configurations (DI containers)
- Review and update custom CSS
- Test all datagrid functionality
- Update any custom templates
- Test with your specific data sources
- Review any custom extensions or traits
Version 5.0.x introduced significant architectural improvements including aggregation functions, multi-action columns, and enhanced filtering capabilities.
Before (v4.x): PHP 5.5+ After (v5.0.x): PHP 5.6+
Impact: High - affects custom button implementations
Before (v4.x):
use Ublaboo\DataGrid\Traits\TButton;
class CustomAction {
use TButton;
}After (v5.0.x):
use Ublaboo\DataGrid\Traits\TButtonIcon;
use Ublaboo\DataGrid\Traits\TButtonClass;
use Ublaboo\DataGrid\Traits\TButtonText;
use Ublaboo\DataGrid\Traits\TButtonTitle;
class CustomAction {
use TButtonIcon, TButtonClass, TButtonText, TButtonTitle;
}Impact: Medium - affects sorting configuration
Before (v4.x):
public function setDefaultSort($sort)After (v5.0.x):
public function setDefaultSort($sort, $use_on_reset = true)Impact: Medium - affects error handling
Before (v4.x):
try {
$column = $grid->getColumn($key);
} catch (DataGridException $e) {
// handle error
}After (v5.0.x):
try {
$column = $grid->getColumn($key);
} catch (DataGridColumnNotFoundException $e) {
// handle missing column
} catch (DataGridFilterNotFoundException $e) {
// handle missing filter
}Impact: Low - affects session management
Before (v4.x):
$grid->deleteSesssionData($key); // Note the typoAfter (v5.0.x):
$grid->deleteSessionData($key); // Fixed typouse Ublaboo\DataGrid\AggregationFunction\FunctionSum;
$grid->addAggregationFunction('total', new FunctionSum('price'));$grid->addMultiAction('actions', 'Actions')
->addAction('edit', 'Edit', 'edit')
->addAction('delete', 'Delete', 'delete');// Individual filter reset
$grid->addFilterText('name', 'Name')
->setCondition('ILIKE ?', '%?%');
// Collapsible outer filters
$grid->setOuterFilterRendering(true);-
Update PHP version to 5.6+
-
Update trait usage:
- Replace
TButtontrait with specific button traits - Update any custom action classes
- Replace
-
Update exception handling:
- Catch specific exception types instead of generic
DataGridException
- Catch specific exception types instead of generic
-
Fix method signatures:
- Update
setDefaultSort()calls if you were extending the class
- Update
-
Fix typos:
- Replace
deleteSesssionData()withdeleteSessionData()
- Replace
-
Test thoroughly:
- Verify all existing functionality works
- Test new features if desired
For large applications, consider a gradual migration:
- Update one major version at a time
- Test thoroughly at each step
- Use feature flags to isolate changes
- Maintain backward compatibility during transition
- Unit tests: Update mocks and test data
- Integration tests: Test with real data sources
- UI tests: Verify visual appearance and behavior
- Performance tests: Ensure no regressions
# Find all files using old namespace
grep -r "Ublaboo\\DataGrid" src/
# Use IDE refactoring tools for bulk updates<!-- Verify correct asset paths -->
<link rel="stylesheet" href="/path/to/datagrid.css">
<script src="/path/to/datagrid.js"></script>// Verify translation keys are updated
$translator = new Nette\Localization\Translator([
'contributte_datagrid.no_items' => 'No items found'
]);If you encounter issues during migration:
- Check the changelog for specific breaking changes
- Review GitHub issues for similar problems
- Create minimal reproduction cases for complex issues
- Consider professional support for large migrations
| Version | PHP Support | Nette Support | Status |
|---|---|---|---|
| 7.1.x | 8.2+ | 3.0+ | Active |
| 7.0.x | 8.2+ | 3.0+ | Maintenance |
| 6.10.x | 7.2-8.3 | 3.0+ | Security fixes only |
| 6.x | 7.2-8.1 | 3.0+ | End of life |
| 5.x | 5.6-7.4 | 2.4-3.0 | End of life |
| 4.x | 5.5-7.1 | 2.3-2.4 | End of life |
For more detailed information about specific changes, see the CHANGELOG.md file.